XSLTPROC_COMMONOPTS = \
--param section.autolabel 1 \
--param section.label.includes.component.label 1 \
- --param chunk.section.depth 0
+ --param chunk.section.depth 0 \
+ --param generate.section.toc.level 1
XSLTPROC_HTMLOPTS = \
--stringparam html.stylesheet style.css \
all: requirements_not_met
endif
-
-postgis-out.xml: postgis.xml long_xact.xml ../Version.config
+postgis-out.xml: postgis.xml introduction.xml installation.xml faq.xml using_postgis.xml performance_tips.xml reference.xml reporting.xml release_notes.xml ../Version.config
cat $< | sed "s/@@LAST_RELEASE_VERSION@@/@POSTGIS_LIB_VERSION@/g" > $@
chunked-html: postgis-out.xml
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Frequently Asked Questions</title>
+
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>What kind of geometric objects can I store?</para>
+ </question>
+
+ <answer>
+ <para>You can store point, line, polygon, multipoint, multiline,
+ multipolygon, and geometrycollections. These are specified in the Open
+ GIS Well Known Text Format (with XYZ,XYM,XYZM extentions).</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How do I insert a GIS object into the database?</para>
+ </question>
+
+ <answer>
+ <para>First, you need to create a table with a column of type
+ "geometry" to hold your GIS data. Connect to your database with
+ <filename>psql</filename> and try the following SQL:</para>
+
+ <programlisting>CREATE TABLE gtest ( ID int4, NAME varchar(20) );
+SELECT AddGeometryColumn('', 'gtest','geom',-1,'LINESTRING',2);</programlisting>
+
+ <para>If the geometry column addition fails, you probably have not
+ loaded the PostGIS functions and objects into this database. See the
+ <link linkend="PGInstall">installation instructions</link>.</para>
+
+ <para>Then, you can insert a geometry into the table using a SQL
+ insert statement. The GIS object itself is formatted using the OpenGIS
+ Consortium "well-known text" format:</para>
+
+ <programlisting>INSERT INTO gtest (ID, NAME, GEOM)
+VALUES (
+ 1,
+ 'First Geometry',
+ GeomFromText('LINESTRING(2 3,4 5,6 5,7 8)', -1)
+);</programlisting>
+
+ <para>For more information about other GIS objects, see the <link
+ linkend="RefObject">object reference</link>.</para>
+
+ <para>To view your GIS data in the table:</para>
+
+ <programlisting>SELECT id, name, AsText(geom) AS geom FROM gtest;</programlisting>
+
+ <para>The return value should look something like this:</para>
+
+ <programlisting> id | name | geom
+----+----------------+-----------------------------
+ 1 | First Geometry | LINESTRING(2 3,4 5,6 5,7 8)
+(1 row)</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How do I construct a spatial query?</para>
+ </question>
+
+ <answer>
+ <para>The same way you construct any other database query, as an SQL
+ combination of return values, functions, and boolean tests.</para>
+
+ <para>For spatial queries, there are two issues that are important to
+ keep in mind while constructing your query: is there a spatial index
+ you can make use of; and, are you doing expensive calculations on a
+ large number of geometries.</para>
+
+ <para>In general, you will want to use the "intersects operator"
+ (&&) which tests whether the bounding boxes of features
+ intersect. The reason the && operator is useful is because if
+ a spatial index is available to speed up the test, the &&
+ operator will make use of this. This can make queries much much
+ faster.</para>
+
+ <para>You will also make use of spatial functions, such as Distance(),
+ ST_Intersects(), ST_Contains() and ST_Within(), among others, to
+ narrow down the results of your search. Most spatial queries include
+ both an indexed test and a spatial function test. The index test
+ serves to limit the number of return tuples to only tuples that
+ <emphasis>might</emphasis> meet the condition of interest. The spatial
+ functions are then use to test the condition exactly.</para>
+
+ <programlisting>SELECT id, the_geom
+FROM thetable
+WHERE
+ the_geom && 'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'
+AND
+ _ST_Contains(the_geom,'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))');</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How do I speed up spatial queries on large tables?</para>
+ </question>
+
+ <answer>
+ <para>Fast queries on large tables is the <emphasis>raison
+ d'etre</emphasis> of spatial databases (along with transaction
+ support) so having a good index is important.</para>
+
+ <para>To build a spatial index on a table with a
+ <varname>geometry</varname> column, use the "CREATE INDEX" function as
+ follows:</para>
+
+ <programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometrycolumn] );</programlisting>
+
+ <para>The "USING GIST" option tells the server to use a GiST
+ (Generalized Search Tree) index.</para>
+
+ <note>
+ <para>GiST indexes are assumed to be lossy. Lossy indexes uses a
+ proxy object (in the spatial case, a bounding box) for building the
+ index.</para>
+ </note>
+
+ <para>You should also ensure that the PostgreSQL query planner has
+ enough information about your index to make rational decisions about
+ when to use it. To do this, you have to "gather statistics" on your
+ geometry tables.</para>
+
+ <para>For PostgreSQL 8.0.x and greater, just run the <command>VACUUM
+ ANALYZE</command> command.</para>
+
+ <para>For PostgreSQL 7.4.x and below, run the <command>SELECT
+ UPDATE_GEOMETRY_STATS()</command> command.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>Why aren't PostgreSQL R-Tree indexes supported?</para>
+ </question>
+
+ <answer>
+ <para>Early versions of PostGIS used the PostgreSQL R-Tree indexes.
+ However, PostgreSQL R-Trees have been completely discarded since
+ version 0.6, and spatial indexing is provided with an R-Tree-over-GiST
+ scheme.</para>
+
+ <para>Our tests have shown search speed for native R-Tree and GiST to
+ be comparable. Native PostgreSQL R-Trees have two limitations which
+ make them undesirable for use with GIS features (note that these
+ limitations are due to the current PostgreSQL native R-Tree
+ implementation, not the R-Tree concept in general):</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>R-Tree indexes in PostgreSQL cannot handle features which
+ are larger than 8K in size. GiST indexes can, using the "lossy"
+ trick of substituting the bounding box for the feature
+ itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>R-Tree indexes in PostgreSQL are not "null safe", so
+ building an index on a geometry column which contains null
+ geometries will fail.</para>
+ </listitem>
+ </itemizedlist>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>Why should I use the <varname>AddGeometryColumn()</varname>
+ function and all the other OpenGIS stuff?</para>
+ </question>
+
+ <answer>
+ <para>If you do not want to use the OpenGIS support functions, you do
+ not have to. Simply create tables as in older versions, defining your
+ geometry columns in the CREATE statement. All your geometries will
+ have SRIDs of -1, and the OpenGIS meta-data tables will
+ <emphasis>not</emphasis> be filled in properly. However, this will
+ cause most applications based on PostGIS to fail, and it is generally
+ suggested that you do use <varname>AddGeometryColumn()</varname> to
+ create geometry tables.</para>
+
+ <para>Mapserver is one application which makes use of the
+ <varname>geometry_columns</varname> meta-data. Specifically, Mapserver
+ can use the SRID of the geometry column to do on-the-fly reprojection
+ of features into the correct map projection.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>What is the best way to find all objects within a radius of
+ another object?</para>
+ </question>
+
+ <answer>
+ <para>To use the database most efficiently, it is best to do radius
+ queries which combine the radius test with a bounding box test: the
+ bounding box test uses the spatial index, giving fast access to a
+ subset of data which the radius test is then applied to.</para>
+
+ <para>The <varname>ST_DWithin(geometry, geometry, distance)</varname>
+ function is a handy way of performing an indexed distance search. It
+ works by creating a search rectangle large enough to enclose the
+ distance radius, then performing an exact distance search on the
+ indexed subset of results.</para>
+
+ <para>For example, to find all objects with 100 meters of POINT(1000
+ 1000) the following query would work well:</para>
+
+ <programlisting>SELECT * FROM geotable
+ WHERE ST_DWithin(geocolumn, 'POINT(1000 1000)', 100.0);</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How do I perform a coordinate reprojection as part of a
+ query?</para>
+ </question>
+
+ <answer>
+ <para>To perform a reprojection, both the source and destination
+ coordinate systems must be defined in the SPATIAL_REF_SYS table, and
+ the geometries being reprojected must already have an SRID set on
+ them. Once that is done, a reprojection is as simple as referring to
+ the desired destination SRID.</para>
+
+ <programlisting>SELECT ST_Transform(the_geom,4269) FROM geotable;</programlisting>
+ </answer>
+ </qandaentry>
+ </qandaset>
+</chapter>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Installation</title>
+
+ <sect1>
+ <title>Requirements</title>
+
+ <para>PostGIS has the following requirements for building and
+ usage:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A complete installation of PostgreSQL (including server
+ headers). PostgreSQL is available from <ulink
+ url="http://www.postgresql.org">http://www.postgresql.org</ulink>.
+ Version 7.2 or higher is required.</para>
+ </listitem>
+
+ <listitem>
+ <para>GNU C compiler (<filename>gcc</filename>). Some other ANSI C
+ compilers can be used to compile PostGIS, but we find far fewer
+ problems when compiling with <filename>gcc</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>GNU Make (<filename>gmake</filename> or
+ <filename>make</filename>). For many systems, GNU
+ <filename>make</filename> is the default version of make. Check the
+ version by invoking <filename>make -v</filename>. Other versions of
+ <filename>make</filename> may not process the PostGIS
+ <filename>Makefile</filename> properly.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Recommended) Proj4 reprojection library. The Proj4 library is
+ used to provide coordinate reprojection support within PostGIS. Proj4
+ is available for download from <ulink
+ url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>(Recommended) GEOS geometry library. The GEOS library is used to
+ provide geometry tests (ST_Touches(), ST_Contains(), ST_Intersects())
+ and operations (ST_Buffer(), ST_Union(), ST_Difference()) within
+ PostGIS. GEOS is available for download from <ulink
+ url="http://geos.refractions.net">http://geos.refractions.net</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="PGInstall">
+ <title>PostGIS</title>
+
+ <para>The PostGIS module is a extension to the PostgreSQL backend server.
+ As such, PostGIS @@LAST_RELEASE_VERSION@@ <emphasis>requires</emphasis>
+ full PostgreSQL server headers access in order to compile. The PostgreSQL
+ source code is available at <ulink
+ url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</para>
+
+ <para>PostGIS @@LAST_RELEASE_VERSION@@ can be built against PostgreSQL
+ versions 7.2.0 or higher. Earlier versions of PostgreSQL are
+ <emphasis>not</emphasis> supported.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Before you can compile the PostGIS server modules, you must
+ compile and install the PostgreSQL package.</para>
+
+ <note>
+ <para>If you plan to use GEOS functionality you might need to
+ explicitly link PostgreSQL against the standard C++ library:</para>
+
+ <programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>
+
+ <para>This is a workaround for bogus C++ exceptions interaction with
+ older development tools. If you experience weird problems (backend
+ unexpectedly closed or similar things) try this trick. This will
+ require recompiling your PostgreSQL from scratch, of course.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>Retrieve the PostGIS source archive from <ulink
+ url="http://postgis.refractions.net/postgis-@@LAST_RELEASE_VERSION@@.tar.gz">http://postgis.refractions.net/postgis-@@LAST_RELEASE_VERSION@@.tar.gz</ulink>.
+ Uncompress and untar the archive.</para>
+
+ <programlisting># gzip -d -c postgis-@@LAST_RELEASE_VERSION@@.tar.gz | tar xvf -</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Enter the postgis-@@LAST_RELEASE_VERSION@@ directory, and run:
+ <programlisting># ./configure</programlisting></para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If you want support for coordinate reprojection, you must
+ have the Proj4 library installed. If ./configure didn't find it,
+ try using <code>--with-proj=PATH</code> switch specify a specific
+ Proj4 installation directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you want to use GEOS functionality, you must have the
+ GEOS library installed. If ./configure didn't find it, try using
+ <code>--with-geos=PATH</code> to specify the full path to the
+ geos-config program full path.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Run the compile and install commands.</para>
+
+ <programlisting># make # make install</programlisting>
+
+ <para>All files are installed using information provided by
+ <filename>pg_config</filename></para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Libraries are installed
+ <filename>[pkglibdir]/lib/contrib</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Important support files such as
+ <filename>lwpostgis.sql</filename> are installed in
+ <filename>[prefix]/share/contrib</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Loader and dumper binaries are installed in
+ <filename>[bindir]/</filename>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>PostGIS requires the PL/pgSQL procedural language extension.
+ Before loading the <filename>lwpostgis.sql</filename> file, you must
+ first enable PL/pgSQL. You should use the
+ <filename>createlang</filename> command. The PostgreSQL Programmer's
+ Guide has the details if you want to this manually for some
+ reason.</para>
+
+ <programlisting># createlang plpgsql [yourdatabase]</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Now load the PostGIS object and function definitions into your
+ database by loading the <filename>lwpostgis.sql</filename> definitions
+ file.</para>
+
+ <programlisting># psql -d [yourdatabase] -f lwpostgis.sql</programlisting>
+
+ <para>The PostGIS server extensions are now loaded and ready to
+ use.</para>
+ </listitem>
+
+ <listitem>
+ <para>For a complete set of EPSG coordinate system definition
+ identifiers, you can also load the
+ <filename>spatial_ref_sys.sql</filename> definitions file and populate
+ the <varname>SPATIAL_REF_SYS</varname> table.</para>
+
+ <programlisting># psql -d [yourdatabase] -f spatial_ref_sys.sql</programlisting>
+ </listitem>
+ </orderedlist>
+
+ <sect2 id="templatepostgis">
+ <title>Creating PostGIS spatially-enabled databases from an in-built
+ template</title>
+
+ <para>Some packaged distributions of PostGIS (in particular the Win32
+ installers for PostGIS >= 1.1.5) load the PostGIS functions into a
+ template database called <varname>template_postgis</varname>. If the
+ <varname>template_postgis</varname> database exists in your PostgreSQL
+ installation then it is possible for users and/or applications to create
+ spatially-enabled databases using a single command. Note that in both
+ cases, the database user must have been granted the privilege to create
+ new databases.</para>
+
+ <para>From the shell:</para>
+
+ <programlisting># createdb -T template_postgis my_spatial_db</programlisting>
+
+ <para>From SQL:</para>
+
+ <programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
+ </sect2>
+
+ <sect2 id="upgrading">
+ <title>Upgrading</title>
+
+ <para>Upgrading existing spatial databases can be tricky as it requires
+ replacement or introduction of new PostGIS object definitions.</para>
+
+ <para>Unfortunately not all definitions can be easily replaced in a live
+ database, so sometimes your best bet is a dump/reload process.</para>
+
+ <para>PostGIS provides a SOFT UPGRADE procedure for minor or bugfix
+ releases, and an HARD UPGRADE procedure for major releases.</para>
+
+ <para>Before attempting to upgrade postgis, it is always worth to backup
+ your data. If you use the -Fc flag to pg_dump you will always be able to
+ restore the dump with an HARD UPGRADE.</para>
+
+ <sect3 id="soft_upgrade">
+ <title>Soft upgrade</title>
+
+ <para>Soft upgrade consists of sourcing the lwpostgis_upgrade.sql
+ script in your spatial database:</para>
+
+ <programlisting>$ psql -f lwpostgis_upgrade.sql -d your_spatial_database</programlisting>
+
+ <para>If a soft upgrade is not possible the script will abort and you
+ will be warned about HARD UPGRADE being required, so do not hesitate
+ to try a soft upgrade first.</para>
+
+ <note>
+ <para>If you can't find the
+ <filename>lwpostgis_upgrade.sql</filename> file you are probably
+ using a version prior to 1.1 and must generate that file by
+ yourself. This is done with the following command:</para>
+
+ <programlisting>$ utils/postgis_proc_upgrade.pl lwpostgis.sql > lwpostgis_upgrade.sql</programlisting>
+ </note>
+ </sect3>
+
+ <sect3 id="hard_upgrade">
+ <title>Hard upgrade</title>
+
+ <para>By HARD UPGRADE we intend full dump/reload of postgis-enabled
+ databases. You need an HARD UPGRADE when postgis objects' internal
+ storage changes or when SOFT UPGRADE is not possible. The <link
+ linkend="release_notes">Release Notes</link> appendix reports for each
+ version whether you need a dump/reload (HARD UPGRADE) to
+ upgrade.</para>
+
+ <para>PostGIS provides an utility script to restore a dump produced
+ with the pg_dump -Fc command. It is experimental so redirecting its
+ output to a file will help in case of problems. The procedure is as
+ follow:</para>
+
+ <para>Create a "custom-format" dump of the database you want to
+ upgrade (let's call it "olddb")</para>
+
+ <programlisting>$ pg_dump -Fc olddb > olddb.dump</programlisting>
+
+ <para>Restore the dump contextually upgrading postgis into a new
+ database. The new database doesn't have to exist. postgis_restore
+ accepts createdb parameters after the dump file name, and that can for
+ instance be used if you are using a non-default character encoding for
+ your database. Let's call it "newdb", with UNICODE as the character
+ encoding:</para>
+
+ <programlisting>$ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump -E=UNICODE > restore.log</programlisting>
+
+ <para>Check that all restored dump objects really had to be restored
+ from dump and do not conflict with the ones defined in
+ lwpostgis.sql</para>
+
+ <programlisting>$ grep ^KEEPING restore.log | less</programlisting>
+
+ <para>If upgrading from PostgreSQL < 8.0 to >= 8.0 you might
+ want to drop the attrelid, varattnum and stats columns in the
+ geometry_columns table, which are no-more needed. Keeping them won't
+ hurt. DROPPING THEM WHEN REALLY NEEDED WILL DO HURT !</para>
+
+ <programlisting>$ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid"
+$ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum"
+$ psql newdb -c "ALTER TABLE geometry_columns DROP stats"</programlisting>
+
+ <para>spatial_ref_sys table is restore from the dump, to ensure your
+ custom additions are kept, but the distributed one might contain
+ modification so you should backup your entries, drop the table and
+ source the new one. If you did make additions we assume you know how
+ to backup them before upgrading the table. Replace of it with the new
+ one is done like this:</para>
+
+ <programlisting>$ psql newdb
+newdb=> drop spatial_ref_sys;
+DROP
+newdb=> \i spatial_ref_sys.sql</programlisting>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Common Problems</title>
+
+ <para>There are several things to check when your installation or
+ upgrade doesn't go as you expected.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>It is easiest if you untar the PostGIS distribution into the
+ contrib directory under the PostgreSQL source tree. However, if this
+ is not possible for some reason, you can set the
+ <varname>PGSQL_SRC</varname> environment variable to the path to the
+ PostgreSQL source directory. This will allow you to compile PostGIS,
+ but the <command>make install</command> may not work, so be prepared
+ to copy the PostGIS library and executable files to the appropriate
+ locations yourself.</para>
+ </listitem>
+
+ <listitem>
+ <para>Check that you you have installed PostgreSQL 7.2 or newer, and
+ that you are compiling against the same version of the PostgreSQL
+ source as the version of PostgreSQL that is running. Mix-ups can
+ occur when your (Linux) distribution has already installed
+ PostgreSQL, or you have otherwise installed PostgreSQL before and
+ forgotten about it. PostGIS will only work with PostgreSQL 7.2 or
+ newer, and strange, unexpected error messages will result if you use
+ an older version. To check the version of PostgreSQL which is
+ running, connect to the database using psql and run this
+ query:</para>
+
+ <programlisting>SELECT version();</programlisting>
+
+ <para>If you are running an RPM based distribution, you can check
+ for the existence of pre-installed packages using the
+ <command>rpm</command> command as follows: <command>rpm -qa | grep
+ postgresql</command></para>
+ </listitem>
+ </orderedlist>
+
+ <para>Also check that you have made any necessary changes to the top of
+ the Makefile.config. This includes:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>If you want to be able to do coordinate reprojections, you
+ must install the Proj4 library on your system, set the
+ <varname>USE_PROJ</varname> variable to 1 and the
+ <varname>PROJ_DIR</varname> to your installation prefix in the
+ Makefile.config.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you want to be able to use GEOS functions you must install
+ the GEOS library on your system, and set the
+ <varname>USE_GEOS</varname> to 1 and the <varname>GEOS_DIR</varname>
+ to your installation prefix in the Makefile.config</para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>JDBC</title>
+
+ <para>The JDBC extensions provide Java objects corresponding to the
+ internal PostGIS types. These objects can be used to write Java clients
+ which query the PostGIS database and draw or do calculations on the GIS
+ data in PostGIS.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Enter the <filename>jdbc</filename> sub-directory of the PostGIS
+ distribution.</para>
+ </listitem>
+
+ <listitem>
+ <para>Edit the <filename>Makefile</filename> to provide the correct
+ paths of your java compiler (<varname>JAVAC</varname>) and interpreter
+ (<varname>JAVA</varname>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Run the <filename>make</filename> command. Copy the
+ <filename>postgis.jar</filename> file to wherever you keep your java
+ libraries.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1>
+ <title>Loader/Dumper</title>
+
+ <para>The data loader and dumper are built and installed automatically as
+ part of the PostGIS build. To build and install them manually:</para>
+
+ <programlisting># cd postgis-@@LAST_RELEASE_VERSION@@/loader
+# make
+# make install</programlisting>
+
+ <para>The loader is called <filename>shp2pgsql</filename> and converts
+ ESRI Shape files into SQL suitable for loading in PostGIS/PostgreSQL. The
+ dumper is called <filename>pgsql2shp</filename> and converts PostGIS
+ tables (or queries) into ESRI Shape files. For more verbose documentation,
+ see the online help, and the manual pages.</para>
+ </sect1>
+</chapter>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Introduction</title>
+
+ <para>PostGIS is developed by Refractions Research Inc, as a spatial
+ database technology research project. Refractions is a GIS and database
+ consulting company in Victoria, British Columbia, Canada, specializing in
+ data integration and custom software development. We plan on supporting and
+ developing PostGIS to support a range of important GIS functionality,
+ including full OpenGIS support, advanced topological constructs (coverages,
+ surfaces, networks), desktop user interface tools for viewing and editing
+ GIS data, and web-based access tools.</para>
+
+ <sect1 id="credits">
+ <title>Credits</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>Sandro Santilli <strk@refractions.net></term>
+
+ <listitem>
+ <para>Coordinates all bug fixing and maintenance effort, integration
+ of new GEOS functionality, and new function enhancements.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Mark Leslie <mleslie@refractions.net></term>
+
+ <listitem>
+ <para>Ongoing maintenance and development of core functions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Chris Hodgson <chodgson@refractions.net></term>
+
+ <listitem>
+ <para>Maintains new functions and the 7.2 index bindings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Paul Ramsey <pramsey@refractions.net></term>
+
+ <listitem>
+ <para>Keeps track of the documentation and packaging.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Jeff Lounsbury <jeffloun@refractions.net></term>
+
+ <listitem>
+ <para>Original development of the Shape file loader/dumper.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Dave Blasby <dblasby@gmail.com></term>
+
+ <listitem>
+ <para>The original developer of PostGIS. Dave wrote the server side
+ objects, index bindings, and many of the server side analytical
+ functions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Other contributors</term>
+
+ <listitem>
+ <para>In alphabetical order: Alex Bodnaru, Alex Mayrhofer, Bruce
+ Rindahl, Bernhard Reiter, Bruno Wolff III, Carl Anderson, Charlie
+ Savage, David Skea, David Techer, IIDA Tetsushi, Geographic Data BC,
+ Gerald Fenoy, Gino Lucrezi, Klaus Foerster, Kris Jurka, Mark
+ Cave-Ayland, Mark Sondheim, Markus Schaber, Michael Fuhr, Nikita
+ Shulga, Norman Vine, Olivier Courtin, Ralph Mason, Steffen
+ Macke.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Important Support Libraries</term>
+
+ <listitem>
+ <para>The <ulink url="http://geos.refractions.net">GEOS</ulink>
+ geometry operations library, and the algorithmic work of Martin
+ Davis <mbdavis@vividsolutions.com> of Vivid Solutions in
+ making it all work.</para>
+
+ <para>The <ulink url="http://proj4.maptools.org">Proj4</ulink>
+ cartographic projection library, and the work of Gerald Evenden and
+ Frank Warmerdam in creating and maintaining it.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>More Information</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The latest software, documentation and news items are available
+ at the PostGIS web site, <ulink
+ url="http://postgis.refractions.net">http://postgis.refractions.net</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>More information about the GEOS geometry operations library is
+ available at<ulink url="http://geos.refractions.net">
+ http://geos.refractions.net</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>More information about the Proj4 reprojection library is
+ available at <ulink
+ url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>More information about the PostgreSQL database server is
+ available at the PostgreSQL main site <ulink
+ url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>More information about GiST indexing is available at the
+ PostgreSQL GiST development site, <ulink
+ url="http://www.sai.msu.su/~megera/postgres/gist">http://www.sai.msu.su/~megera/postgres/gist</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>More information about Mapserver internet map server is
+ available at <ulink
+ url="http://mapserver.gis.umn.edu/">http://mapserver.gis.umn.edu</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The "<ulink url="http://www.opengis.org/docs/99-049.pdf">Simple
+ Features for Specification for SQL</ulink>" is available at the
+ OpenGIS Consortium web site: <ulink
+ url="http://www.opengis.org">http://www.opengis.org</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+</chapter>
\ No newline at end of file
+++ /dev/null
- <sect2>
- <title>Long Transactions support</title>
-
- <para>
-This module and associated pl/pgsql functions have been implemented
-to provide long locking support required by
-<ulink url="https://portal.opengeospatial.org/files/?artifact_id=7176">Web Feature Service</ulink> specification.
- </para>
-
- <note>
- <para>
- Users must use <ulink url="http://www.postgresql.org/docs/7.4/static/transaction-iso.html">serializable transaction level</ulink> otherwise locking mechanism would break.
- </para>
- </note>
-
- <variablelist>
-
- <varlistentry id="EnableLongTransactions">
- <term>EnableLongTransactions()</term>
- <listitem>
- <para>
- Enable long transaction support. This function creates the
- required metadata tables, needs to be called once before
- using the other functions in this section. Calling it twice
- is harmless.
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="DisableLongTransactions">
- <term>DisableLongTransactions()</term>
- <listitem>
- <para>
- Disable long transaction support. This function removes the
- long transaction support metadata tables, and drops all
- triggers attached to lock-checked tables.
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="CheckAuth">
- <term>CheckAuth([<schema>], <table>, <rowid_col>)</term>
- <listitem>
- <para>
- Check updates and deletes of rows in
- given table for being authorized.
- Identify rows using <rowid_col> column.
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="LockRow">
- <term>LockRow([<schema>], <table>, <rowid>, <authid>, [<expires>])</term>
- <listitem>
- <para>
- Set lock/authorization for specific row in table
- <authid> is a text value, <expires> is a timestamp
- defaulting to now()+1hour.
- Returns 1 if lock has been assigned, 0 otherwise
- (already locked by other auth)
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="UnlockRows">
- <term>UnlockRows(<authid>)</term>
- <listitem>
- <para>
- Remove all locks held by specified authorization id.
- Returns the number of locks released.
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="AddAuth">
- <term>AddAuth(<authid>)</term>
- <listitem>
- <para>
- Add an authorization token to be used in current
- transaction.
- </para>
- <para>
- Availability: 1.1.3
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </sect2>
-
-
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Performance tips</title>
+
+ <sect1>
+ <title>Small tables of large geometries</title>
+
+ <sect2>
+ <title>Problem description</title>
+
+ <para>Current PostgreSQL versions (including 8.0) suffer from a query
+ optimizer weakness regarding TOAST tables. TOAST tables are a kind of
+ "extension room" used to store large (in the sense of data size) values
+ that do not fit into normal data pages (like long texts, images or
+ complex geometries with lots of vertices), see
+ http://www.postgresql.org/docs/8.0/static/storage-toast.html for more
+ information).</para>
+
+ <para>The problem appears if you happen to have a table with rather
+ large geometries, but not too much rows of them (like a table containing
+ the boundaries of all European countries in high resolution). Then the
+ table itself is small, but it uses lots of TOAST space. In our example
+ case, the table itself had about 80 rows and used only 3 data pages, but
+ the TOAST table used 8225 pages.</para>
+
+ <para>Now issue a query where you use the geometry operator &&
+ to search for a bounding box that matches only very few of those rows.
+ Now the query optimizer sees that the table has only 3 pages and 80
+ rows. He estimates that a sequential scan on such a small table is much
+ faster than using an index. And so he decides to ignore the GIST index.
+ Usually, this estimation is correct. But in our case, the &&
+ operator has to fetch every geometry from disk to compare the bounding
+ boxes, thus reading all TOAST pages, too.</para>
+
+ <para>To see whether your suffer from this bug, use the "EXPLAIN
+ ANALYZE" postgresql command. For more information and the technical
+ details, you can read the thread on the postgres performance mailing
+ list:
+ http://archives.postgresql.org/pgsql-performance/2005-02/msg00030.php</para>
+ </sect2>
+
+ <sect2>
+ <title>Workarounds</title>
+
+ <para>The PostgreSQL people are trying to solve this issue by making the
+ query estimation TOAST-aware. For now, here are two workarounds:</para>
+
+ <para>The first workaround is to force the query planner to use the
+ index. Send "SET enable_seqscan TO off;" to the server before issuing
+ the query. This basically forces the query planner to avoid sequential
+ scans whenever possible. So it uses the GIST index as usual. But this
+ flag has to be set on every connection, and it causes the query planner
+ to make misestimations in other cases, so you should "SET enable_seqscan
+ TO on;" after the query.</para>
+
+ <para>The second workaround is to make the sequential scan as fast as
+ the query planner thinks. This can be achieved by creating an additional
+ column that "caches" the bbox, and matching against this. In our
+ example, the commands are like:</para>
+
+ <programlisting>SELECT AddGeometryColumn('myschema','mytable','bbox','4326','GEOMETRY','2');
+UPDATE mytable SET bbox = ST_Envelope(ST_Force_2d(the_geom));</programlisting>
+
+ <para>Now change your query to use the && operator against bbox
+ instead of geom_column, like:</para>
+
+ <programlisting>SELECT geom_column
+FROM mytable
+WHERE bbox && ST_SetSRID('BOX3D(0 0,1 1)'::box3d,4326);</programlisting>
+
+ <para>Of course, if you change or add rows to mytable, you have to keep
+ the bbox "in sync". The most transparent way to do this would be
+ triggers, but you also can modify your application to keep the bbox
+ column current or run the UPDATE query above after every
+ modification.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>CLUSTERing on geometry indices</title>
+
+ <para>For tables that are mostly read-only, and where a single index is
+ used for the majority of queries, PostgreSQL offers the CLUSTER command.
+ This command physically reorders all the data rows in the same order as
+ the index criteria, yielding two performance advantages: First, for index
+ range scans, the number of seeks on the data table is drastically reduced.
+ Second, if your working set concentrates to some small intervals on the
+ indices, you have a more efficient caching because the data rows are
+ spread along fewer data pages. (Feel invited to read the CLUSTER command
+ documentation from the PostgreSQL manual at this point.)</para>
+
+ <para>However, currently PostgreSQL does not allow clustering on PostGIS
+ GIST indices because GIST indices simply ignores NULL values, you get an
+ error message like:</para>
+
+ <programlisting>lwgeom=# CLUSTER my_geom_index ON my_table;
+ERROR: cannot cluster when index access method does not handle null values
+HINT: You may be able to work around this by marking column "the_geom" NOT NULL.</programlisting>
+
+ <para>As the HINT message tells you, one can work around this deficiency
+ by adding a "not null" constraint to the table:</para>
+
+ <programlisting>lwgeom=# ALTER TABLE my_table ALTER COLUMN the_geom SET not null;
+ALTER TABLE</programlisting>
+
+ <para>Of course, this will not work if you in fact need NULL values in
+ your geometry column. Additionally, you must use the above method to add
+ the constraint, using a CHECK constraint like "ALTER TABLE blubb ADD CHECK
+ (geometry is not null);" will not work.</para>
+ </sect1>
+
+ <sect1>
+ <title>Avoiding dimension conversion</title>
+
+ <para>Sometimes, you happen to have 3D or 4D data in your table, but
+ always access it using OpenGIS compliant ST_AsText() or ST_AsBinary()
+ functions that only output 2D geometries. They do this by internally
+ calling the ST_Force_2d() function, which introduces a significant
+ overhead for large geometries. To avoid this overhead, it may be feasible
+ to pre-drop those additional dimensions once and forever:</para>
+
+ <programlisting>UPDATE mytable SET the_geom = ST_Force_2d(the_geom);
+VACUUM FULL ANALYZE mytable;</programlisting>
+
+ <para>Note that if you added your geometry column using
+ AddGeometryColumn() there'll be a constraint on geometry dimension. To
+ bypass it you will need to drop the constraint. Remember to update the
+ entry in the geometry_columns table and recreate the constraint
+ afterwards.</para>
+
+ <para>In case of large tables, it may be wise to divide this UPDATE into
+ smaller portions by constraining the UPDATE to a part of the table via a
+ WHERE clause and your primary key or another feasible criteria, and
+ running a simple "VACUUM;" between your UPDATEs. This drastically reduces
+ the need for temporary disk space. Additionally, if you have mixed
+ dimension geometries, restricting the UPDATE by "WHERE
+ dimension(the_geom)>2" skips re-writing of geometries that already are
+ in 2D.</para>
+ </sect1>
+</chapter>
\ No newline at end of file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY long_xact SYSTEM "long_xact.xml">
+
+<!ENTITY introduction SYSTEM "introduction.xml">
+<!ENTITY installation SYSTEM "installation.xml">
+<!ENTITY faq SYSTEM "faq.xml">
+<!ENTITY using_postgis SYSTEM "using_postgis.xml">
+<!ENTITY performance_tips SYSTEM "performance_tips.xml">
+<!ENTITY reference SYSTEM "reference.xml">
+<!ENTITY reporting SYSTEM "reporting.xml">
+<!ENTITY release_notes SYSTEM "release_notes.xml">
+
]>
<book>
<title>PostGIS @@LAST_RELEASE_VERSION@@ Manual</title>
</abstract>
</bookinfo>
- <chapter>
- <title>Introduction</title>
-
- <para>PostGIS is developed by Refractions Research Inc, as a spatial
- database technology research project. Refractions is a GIS and database
- consulting company in Victoria, British Columbia, Canada, specializing in
- data integration and custom software development. We plan on supporting
- and developing PostGIS to support a range of important GIS functionality,
- including full OpenGIS support, advanced topological constructs
- (coverages, surfaces, networks), desktop user interface tools for viewing
- and editing GIS data, and web-based access tools.</para>
-
- <sect1 id="credits">
- <title>Credits</title>
-
- <variablelist>
- <varlistentry>
- <term>Sandro Santilli <strk@refractions.net></term>
-
- <listitem>
- <para>Coordinates all bug fixing and maintenance effort,
- integration of new GEOS functionality, and new function
- enhancements.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Mark Leslie <mleslie@refractions.net></term>
- <listitem>
- <para>Ongoing maintenance and development of core functions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Chris Hodgson <chodgson@refractions.net></term>
-
- <listitem>
- <para>Maintains new functions and the 7.2 index bindings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Paul Ramsey <pramsey@refractions.net></term>
-
- <listitem>
- <para>Keeps track of the documentation and packaging.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Jeff Lounsbury <jeffloun@refractions.net></term>
-
- <listitem>
- <para>Original development of the Shape file loader/dumper.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Dave Blasby <dblasby@gmail.com></term>
-
- <listitem>
- <para>The original developer of PostGIS. Dave wrote the server
- side objects, index bindings, and many of the server side
- analytical functions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Other contributors</term>
-
- <listitem>
- <para>In alphabetical order: Alex Bodnaru, Alex Mayrhofer, Bruce
- Rindahl, Bernhard Reiter, Bruno Wolff III, Carl Anderson, Charlie
- Savage, David Skea, David Techer, IIDA Tetsushi, Geographic Data
- BC, Gerald Fenoy, Gino Lucrezi, Klaus Foerster, Kris Jurka, Mark
- Cave-Ayland, Mark Sondheim, Markus Schaber, Michael Fuhr, Nikita
- Shulga, Norman Vine, Olivier Courtin, Ralph Mason, Steffen Macke.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Important Support Libraries</term>
-
- <listitem>
- <para>The <ulink url="http://geos.refractions.net">GEOS</ulink>
- geometry operations library, and the algorithmic work of Martin
- Davis <mbdavis@vividsolutions.com> of Vivid Solutions in
- making it all work.</para>
-
- <para>The <ulink url="http://proj4.maptools.org">Proj4</ulink>
- cartographic projection library, and the work of Gerald Evenden
- and Frank Warmerdam in creating and maintaining it.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1>
- <title>More Information</title>
-
- <itemizedlist>
- <listitem>
- <para>The latest software, documentation and news items are
- available at the PostGIS web site, <ulink
- url="http://postgis.refractions.net">http://postgis.refractions.net</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>More information about the GEOS geometry operations library is
- available at<ulink url="http://geos.refractions.net">
- http://geos.refractions.net</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>More information about the Proj4 reprojection library is
- available at <ulink url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>More information about the PostgreSQL database server is
- available at the PostgreSQL main site <ulink
- url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>More information about GiST indexing is available at the
- PostgreSQL GiST development site, <ulink
- url="http://www.sai.msu.su/~megera/postgres/gist">http://www.sai.msu.su/~megera/postgres/gist</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>More information about Mapserver internet map server is
- available at <ulink url="http://mapserver.gis.umn.edu/">http://mapserver.gis.umn.edu</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>The "<ulink url="http://www.opengis.org/docs/99-049.pdf">Simple
- Features for Specification for SQL</ulink>" is available at the
- OpenGIS Consortium web site: <ulink url="http://www.opengis.org">http://www.opengis.org</ulink>.</para>
- </listitem>
- </itemizedlist>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Installation</title>
-
- <sect1>
- <title>Requirements</title>
-
- <para>PostGIS has the following requirements for building and usage:</para>
-
- <itemizedlist>
- <listitem>
- <para>A complete installation of PostgreSQL (including server
- headers). PostgreSQL is available from <ulink
- url="http://www.postgresql.org">http://www.postgresql.org</ulink>.
- Version 7.2 or higher is required.</para>
- </listitem>
-
- <listitem>
- <para>GNU C compiler (<filename>gcc</filename>). Some other ANSI C
- compilers can be used to compile PostGIS, but we find far fewer
- problems when compiling with <filename>gcc</filename>.</para>
- </listitem>
-
- <listitem>
- <para>GNU Make (<filename>gmake</filename> or <filename>make</filename>).
- For many systems, GNU <filename>make</filename> is the default
- version of make. Check the version by invoking <filename>make -v</filename>.
- Other versions of <filename>make</filename> may not process the
- PostGIS <filename>Makefile</filename> properly.</para>
- </listitem>
-
- <listitem>
- <para>(Recommended) Proj4 reprojection library. The Proj4 library is
- used to provide coordinate reprojection support within PostGIS.
- Proj4 is available for download from <ulink
- url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>(Recommended) GEOS geometry library. The GEOS library is used
- to provide geometry tests (ST_Touches(), ST_Contains(), ST_Intersects()) and
- operations (ST_Buffer(), ST_Union(), ST_Difference()) within PostGIS.
- GEOS is available for download from <ulink
- url="http://geos.refractions.net">http://geos.refractions.net</ulink>.</para>
- </listitem>
- </itemizedlist>
- </sect1>
-
- <sect1 id="PGInstall">
- <title>PostGIS</title>
-
- <para>The PostGIS module is a extension to the PostgreSQL backend
- server. As such, PostGIS @@LAST_RELEASE_VERSION@@ <emphasis>requires</emphasis>
- full PostgreSQL server headers access in order to compile. The
- PostgreSQL source code is available at <ulink
- url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</para>
-
- <para>PostGIS @@LAST_RELEASE_VERSION@@ can be built against PostgreSQL
- versions 7.2.0 or higher. Earlier versions of PostgreSQL are
- <emphasis>not</emphasis> supported.</para>
-
- <orderedlist>
- <listitem>
- <para>Before you can compile the PostGIS server modules, you must
- compile and install the PostgreSQL package.</para>
-
- <note>
- <para>If you plan to use GEOS functionality you might need to
- explicitly link PostgreSQL against the standard C++ library:</para>
-
- <programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>
-
- <para>This is a workaround for bogus C++ exceptions interaction
- with older development tools. If you experience weird problems
- (backend unexpectedly closed or similar things) try this trick.
- This will require recompiling your PostgreSQL from scratch, of
- course.</para>
- </note>
- </listitem>
-
- <listitem>
- <para>Retrieve the PostGIS source archive from <ulink
- url="http://postgis.refractions.net/postgis-@@LAST_RELEASE_VERSION@@.tar.gz">http://postgis.refractions.net/postgis-@@LAST_RELEASE_VERSION@@.tar.gz</ulink>.
- Uncompress and untar the archive.</para>
-
- <programlisting># gzip -d -c postgis-@@LAST_RELEASE_VERSION@@.tar.gz | tar xvf -</programlisting>
- </listitem>
-
- <listitem>
- <para>Enter the postgis-@@LAST_RELEASE_VERSION@@ directory, and run:
- <programlisting># ./configure</programlisting></para>
-
- <itemizedlist>
- <listitem>
- <para>If you want support for coordinate reprojection, you must
- have the Proj4 library installed. If ./configure didn't find
- it, try using <code>--with-proj=PATH</code> switch specify a
- specific Proj4 installation directory.</para>
- </listitem>
-
- <listitem>
- <para>If you want to use GEOS functionality, you must have the
- GEOS library installed. If ./configure didn't find it, try
- using <code>--with-geos=PATH</code> to specify the full path to
- the geos-config program full path.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Run the compile and install commands.</para>
-
- <programlisting># make # make install</programlisting>
-
- <para>All files are installed using information provided by
- <filename>pg_config</filename></para>
-
- <itemizedlist>
- <listitem>
- <para>Libraries are installed <filename>[pkglibdir]/lib/contrib</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Important support files such as <filename>lwpostgis.sql</filename>
- are installed in <filename>[prefix]/share/contrib</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Loader and dumper binaries are installed in
- <filename>[bindir]/</filename>.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>PostGIS requires the PL/pgSQL procedural language extension.
- Before loading the <filename>lwpostgis.sql</filename> file, you must
- first enable PL/pgSQL. You should use the <filename>createlang</filename>
- command. The PostgreSQL Programmer's Guide has the details if
- you want to this manually for some reason.</para>
-
- <programlisting># createlang plpgsql [yourdatabase]</programlisting>
- </listitem>
-
- <listitem>
- <para>Now load the PostGIS object and function definitions into your
- database by loading the <filename>lwpostgis.sql</filename>
- definitions file.</para>
-
- <programlisting># psql -d [yourdatabase] -f lwpostgis.sql</programlisting>
-
- <para>The PostGIS server extensions are now loaded and ready to use.</para>
- </listitem>
-
- <listitem>
- <para>For a complete set of EPSG coordinate system definition
- identifiers, you can also load the <filename>spatial_ref_sys.sql</filename>
- definitions file and populate the <varname>SPATIAL_REF_SYS</varname>
- table.</para>
-
- <programlisting># psql -d [yourdatabase] -f spatial_ref_sys.sql</programlisting>
- </listitem>
- </orderedlist>
-
- <sect2 id="templatepostgis">
- <title>Creating PostGIS spatially-enabled databases from an in-built
- template</title>
-
- <para>Some packaged distributions of PostGIS (in particular the Win32
- installers for PostGIS >= 1.1.5) load the PostGIS functions into a
- template database called <varname>template_postgis</varname>. If the
- <varname>template_postgis</varname> database exists in your PostgreSQL
- installation then it is possible for users and/or applications to
- create spatially-enabled databases using a single command. Note that
- in both cases, the database user must have been granted the privilege
- to create new databases.</para>
-
- <para>From the shell:</para>
-
- <programlisting># createdb -T template_postgis my_spatial_db</programlisting>
-
- <para>From SQL:</para>
-
- <programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
- </sect2>
-
- <sect2 id="upgrading">
- <title>Upgrading</title>
-
- <para>Upgrading existing spatial databases can be tricky as it
- requires replacement or introduction of new PostGIS object
- definitions.</para>
-
- <para>Unfortunately not all definitions can be easily replaced in a
- live database, so sometimes your best bet is a dump/reload process.</para>
-
- <para>PostGIS provides a SOFT UPGRADE procedure for minor or bugfix
- releases, and an HARD UPGRADE procedure for major releases.</para>
-
- <para>Before attempting to upgrade postgis, it is always worth to
- backup your data. If you use the -Fc flag to pg_dump you will always
- be able to restore the dump with an HARD UPGRADE.</para>
-
- <sect3 id="soft_upgrade">
- <title>Soft upgrade</title>
-
- <para>Soft upgrade consists of sourcing the lwpostgis_upgrade.sql
- script in your spatial database:</para>
-
- <programlisting>$ psql -f lwpostgis_upgrade.sql -d your_spatial_database</programlisting>
-
- <para>If a soft upgrade is not possible the script will abort and
- you will be warned about HARD UPGRADE being required, so do not
- hesitate to try a soft upgrade first.</para>
-
- <note>
- <para>If you can't find the <filename>lwpostgis_upgrade.sql</filename>
- file you are probably using a version prior to 1.1 and must
- generate that file by yourself. This is done with the following
- command:</para>
-
- <programlisting>$ utils/postgis_proc_upgrade.pl lwpostgis.sql > lwpostgis_upgrade.sql</programlisting>
- </note>
- </sect3>
-
- <sect3 id="hard_upgrade">
- <title>Hard upgrade</title>
-
- <para>By HARD UPGRADE we intend full dump/reload of postgis-enabled
- databases. You need an HARD UPGRADE when postgis objects'
- internal storage changes or when SOFT UPGRADE is not possible. The
- <link linkend="release_notes">Release Notes</link> appendix reports
- for each version whether you need a dump/reload (HARD UPGRADE) to
- upgrade.</para>
-
- <para>PostGIS provides an utility script to restore a dump produced
- with the pg_dump -Fc command. It is experimental so redirecting its
- output to a file will help in case of problems. The procedure is as
- follow:</para>
-
- <para>Create a "custom-format" dump of the database you want
- to upgrade (let's call it "olddb")</para>
-
- <programlisting>$ pg_dump -Fc olddb > olddb.dump</programlisting>
-
- <para>Restore the dump contextually upgrading postgis into a new
- database. The new database doesn't have to exist.
- postgis_restore accepts createdb parameters after the dump file
- name, and that can for instance be used if you are using a
- non-default character encoding for your database. Let's call it
- "newdb", with UNICODE as the character encoding:</para>
-
- <programlisting>$ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump -E=UNICODE > restore.log</programlisting>
-
- <para>Check that all restored dump objects really had to be restored
- from dump and do not conflict with the ones defined in lwpostgis.sql</para>
-
- <programlisting>$ grep ^KEEPING restore.log | less</programlisting>
-
- <para>If upgrading from PostgreSQL < 8.0 to >= 8.0 you might
- want to drop the attrelid, varattnum and stats columns in the
- geometry_columns table, which are no-more needed. Keeping them
- won't hurt. DROPPING THEM WHEN REALLY NEEDED WILL DO HURT !</para>
-
- <programlisting>$ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid"
-$ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum"
-$ psql newdb -c "ALTER TABLE geometry_columns DROP stats"</programlisting>
-
- <para>spatial_ref_sys table is restore from the dump, to ensure your
- custom additions are kept, but the distributed one might contain
- modification so you should backup your entries, drop the table and
- source the new one. If you did make additions we assume you know how
- to backup them before upgrading the table. Replace of it with the
- new one is done like this:</para>
-
- <programlisting>$ psql newdb
-newdb=> drop spatial_ref_sys;
-DROP
-newdb=> \i spatial_ref_sys.sql</programlisting>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Common Problems</title>
-
- <para>There are several things to check when your installation or
- upgrade doesn't go as you expected.</para>
-
- <orderedlist>
- <listitem>
- <para>It is easiest if you untar the PostGIS distribution into the
- contrib directory under the PostgreSQL source tree. However, if
- this is not possible for some reason, you can set the
- <varname>PGSQL_SRC</varname> environment variable to the path to
- the PostgreSQL source directory. This will allow you to compile
- PostGIS, but the <command>make install</command> may not work, so
- be prepared to copy the PostGIS library and executable files to
- the appropriate locations yourself.</para>
- </listitem>
-
- <listitem>
- <para>Check that you you have installed PostgreSQL 7.2 or newer,
- and that you are compiling against the same version of the
- PostgreSQL source as the version of PostgreSQL that is running.
- Mix-ups can occur when your (Linux) distribution has already
- installed PostgreSQL, or you have otherwise installed PostgreSQL
- before and forgotten about it. PostGIS will only work with
- PostgreSQL 7.2 or newer, and strange, unexpected error messages
- will result if you use an older version. To check the version of
- PostgreSQL which is running, connect to the database using psql
- and run this query:</para>
-
- <programlisting>SELECT version();</programlisting>
-
- <para>If you are running an RPM based distribution, you can check
- for the existence of pre-installed packages using the
- <command>rpm</command> command as follows: <command>rpm -qa | grep
- postgresql</command></para>
- </listitem>
- </orderedlist>
-
- <para>Also check that you have made any necessary changes to the top
- of the Makefile.config. This includes:</para>
-
- <orderedlist>
- <listitem>
- <para>If you want to be able to do coordinate reprojections, you
- must install the Proj4 library on your system, set the
- <varname>USE_PROJ</varname> variable to 1 and the
- <varname>PROJ_DIR</varname> to your installation prefix in the
- Makefile.config.</para>
- </listitem>
-
- <listitem>
- <para>If you want to be able to use GEOS functions you must
- install the GEOS library on your system, and set the
- <varname>USE_GEOS</varname> to 1 and the <varname>GEOS_DIR</varname>
- to your installation prefix in the Makefile.config</para>
- </listitem>
- </orderedlist>
- </sect2>
- </sect1>
-
- <sect1>
- <title>JDBC</title>
-
- <para>The JDBC extensions provide Java objects corresponding to the
- internal PostGIS types. These objects can be used to write Java clients
- which query the PostGIS database and draw or do calculations on the GIS
- data in PostGIS.</para>
-
- <orderedlist>
- <listitem>
- <para>Enter the <filename>jdbc</filename> sub-directory of the
- PostGIS distribution.</para>
- </listitem>
-
- <listitem>
- <para>Edit the <filename>Makefile</filename> to provide the correct
- paths of your java compiler (<varname>JAVAC</varname>) and
- interpreter (<varname>JAVA</varname>).</para>
- </listitem>
-
- <listitem>
- <para>Run the <filename>make</filename> command. Copy the
- <filename>postgis.jar</filename> file to wherever you keep your java
- libraries.</para>
- </listitem>
- </orderedlist>
- </sect1>
-
- <sect1>
- <title>Loader/Dumper</title>
-
- <para>The data loader and dumper are built and installed automatically
- as part of the PostGIS build. To build and install them manually:</para>
-
- <programlisting># cd postgis-@@LAST_RELEASE_VERSION@@/loader
-# make
-# make install</programlisting>
-
- <para>The loader is called <filename>shp2pgsql</filename> and converts
- ESRI Shape files into SQL suitable for loading in PostGIS/PostgreSQL.
- The dumper is called <filename>pgsql2shp</filename> and converts PostGIS
- tables (or queries) into ESRI Shape files. For more verbose
- documentation, see the online help, and the manual pages.</para>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Frequently Asked Questions</title>
-
- <qandaset>
- <qandaentry>
- <question>
- <para>What kind of geometric objects can I store?</para>
- </question>
-
- <answer>
- <para>You can store point, line, polygon, multipoint, multiline,
- multipolygon, and geometrycollections. These are specified in the
- Open GIS Well Known Text Format (with XYZ,XYM,XYZM extentions).</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I insert a GIS object into the database?</para>
- </question>
-
- <answer>
- <para>First, you need to create a table with a column of type
- "geometry" to hold your GIS data. Connect to your database
- with <filename>psql</filename> and try the following SQL:</para>
-
- <programlisting>CREATE TABLE gtest ( ID int4, NAME varchar(20) );
-SELECT AddGeometryColumn('', 'gtest','geom',-1,'LINESTRING',2);</programlisting>
-
- <para>If the geometry column addition fails, you probably have not
- loaded the PostGIS functions and objects into this database. See the
- <link linkend="PGInstall">installation instructions</link>.</para>
-
- <para>Then, you can insert a geometry into the table using a SQL
- insert statement. The GIS object itself is formatted using the
- OpenGIS Consortium "well-known text" format:</para>
-
- <programlisting>INSERT INTO gtest (ID, NAME, GEOM)
-VALUES (
- 1,
- 'First Geometry',
- GeomFromText('LINESTRING(2 3,4 5,6 5,7 8)', -1)
-);</programlisting>
-
- <para>For more information about other GIS objects, see the <link
- linkend="RefObject">object reference</link>.</para>
-
- <para>To view your GIS data in the table:</para>
-
- <programlisting>SELECT id, name, AsText(geom) AS geom FROM gtest;</programlisting>
-
- <para>The return value should look something like this:</para>
-
- <programlisting> id | name | geom
-----+----------------+-----------------------------
- 1 | First Geometry | LINESTRING(2 3,4 5,6 5,7 8)
-(1 row)</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I construct a spatial query?</para>
- </question>
-
- <answer>
- <para>The same way you construct any other database query, as an SQL
- combination of return values, functions, and boolean tests.</para>
-
- <para>For spatial queries, there are two issues that are important
- to keep in mind while constructing your query: is there a spatial
- index you can make use of; and, are you doing expensive calculations
- on a large number of geometries.</para>
-
- <para>In general, you will want to use the "intersects
- operator" (&&) which tests whether the bounding boxes of
- features intersect. The reason the && operator is useful is
- because if a spatial index is available to speed up the test, the
- && operator will make use of this. This can make queries
- much much faster.</para>
-
- <para>You will also make use of spatial functions, such as
- Distance(), ST_Intersects(), ST_Contains() and ST_Within(),
- among others, to
- narrow down the results of your search. Most spatial queries include
- both an indexed test and a spatial function test. The index test
- serves to limit the number of return tuples to only tuples that
- <emphasis>might</emphasis> meet the condition of interest. The
- spatial functions are then use to test the condition exactly.</para>
-
- <programlisting>SELECT id, the_geom
-FROM thetable
-WHERE
- the_geom && 'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'
-AND
- _ST_Contains(the_geom,'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))');</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I speed up spatial queries on large tables?</para>
- </question>
-
- <answer>
- <para>Fast queries on large tables is the <emphasis>raison
- d'etre</emphasis> of spatial databases (along with transaction
- support) so having a good index is important.</para>
-
- <para>To build a spatial index on a table with a <varname>geometry</varname>
- column, use the "CREATE INDEX" function as follows:</para>
-
- <programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometrycolumn] );</programlisting>
-
- <para>The "USING GIST" option tells the server to use a GiST
- (Generalized Search Tree) index.</para>
-
- <note>
- <para>GiST indexes are assumed to be lossy. Lossy indexes uses a
- proxy object (in the spatial case, a bounding box) for building
- the index.</para>
- </note>
-
- <para>You should also ensure that the PostgreSQL query planner has
- enough information about your index to make rational decisions about
- when to use it. To do this, you have to "gather statistics"
- on your geometry tables.</para>
-
- <para>For PostgreSQL 8.0.x and greater, just run the
- <command>VACUUM ANALYZE</command> command.</para>
-
- <para>For PostgreSQL 7.4.x and below, run the <command>SELECT
- UPDATE_GEOMETRY_STATS()</command> command.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Why aren't PostgreSQL R-Tree indexes supported?</para>
- </question>
-
- <answer>
- <para>Early versions of PostGIS used the PostgreSQL R-Tree indexes.
- However, PostgreSQL R-Trees have been completely discarded since
- version 0.6, and spatial indexing is provided with an
- R-Tree-over-GiST scheme.</para>
-
- <para>Our tests have shown search speed for native R-Tree and GiST
- to be comparable. Native PostgreSQL R-Trees have two limitations
- which make them undesirable for use with GIS features (note that
- these limitations are due to the current PostgreSQL native R-Tree
- implementation, not the R-Tree concept in general):</para>
-
- <itemizedlist>
- <listitem>
- <para>R-Tree indexes in PostgreSQL cannot handle features which
- are larger than 8K in size. GiST indexes can, using the
- "lossy" trick of substituting the bounding box for the
- feature itself.</para>
- </listitem>
-
- <listitem>
- <para>R-Tree indexes in PostgreSQL are not "null safe",
- so building an index on a geometry column which contains null
- geometries will fail.</para>
- </listitem>
- </itemizedlist>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Why should I use the <varname>AddGeometryColumn()</varname>
- function and all the other OpenGIS stuff?</para>
- </question>
-
- <answer>
- <para>If you do not want to use the OpenGIS support functions, you
- do not have to. Simply create tables as in older versions, defining
- your geometry columns in the CREATE statement. All your geometries
- will have SRIDs of -1, and the OpenGIS meta-data tables will
- <emphasis>not</emphasis> be filled in properly. However, this will
- cause most applications based on PostGIS to fail, and it is
- generally suggested that you do use <varname>AddGeometryColumn()</varname>
- to create geometry tables.</para>
-
- <para>Mapserver is one application which makes use of the
- <varname>geometry_columns</varname> meta-data. Specifically,
- Mapserver can use the SRID of the geometry column to do on-the-fly
- reprojection of features into the correct map projection.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What is the best way to find all objects within a radius of
- another object?</para>
- </question>
-
- <answer>
- <para>To use the database most efficiently, it is best to do radius
- queries which combine the radius test with a bounding box test: the
- bounding box test uses the spatial index, giving fast access to a
- subset of data which the radius test is then applied to.</para>
-
- <para>The <varname>ST_DWithin(geometry, geometry, distance)</varname>
- function is a handy way of performing an indexed distance search.
- It works by creating a search rectangle large enough to enclose the
- distance radius, then performing an exact distance search on the
- indexed subset of results.</para>
-
- <para>For example, to find all objects with 100 meters of POINT(1000
- 1000) the following query would work well:</para>
-
- <programlisting>SELECT * FROM geotable
- WHERE ST_DWithin(geocolumn, 'POINT(1000 1000)', 100.0);</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How do I perform a coordinate reprojection as part of a query?</para>
- </question>
-
- <answer>
- <para>To perform a reprojection, both the source and destination
- coordinate systems must be defined in the SPATIAL_REF_SYS table, and
- the geometries being reprojected must already have an SRID set on
- them. Once that is done, a reprojection is as simple as referring to
- the desired destination SRID.</para>
-
- <programlisting>SELECT ST_Transform(the_geom,4269) FROM geotable;</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
- </chapter>
-
- <chapter>
- <title>Using PostGIS</title>
-
- <sect1 id="RefObject">
- <title>GIS Objects</title>
-
- <para>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.</para>
-
- <para>PostGIS extends the standard with support for 3DZ,3DM and 4D
- coordinates.</para>
-
- <sect2>
- <title>OpenGIS WKB and WKT</title>
-
- <para>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.</para>
-
- <para>Examples of the text representations (WKT) of the spatial
- objects of the features are as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>POINT(0 0)</para>
- </listitem>
-
- <listitem>
- <para>LINESTRING(0 0,1 1,1 2)</para>
- </listitem>
-
- <listitem>
- <para>POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))</para>
- </listitem>
-
- <listitem>
- <para>MULTIPOINT(0 0,1 2)</para>
- </listitem>
-
- <listitem>
- <para>MULTILINESTRING((0 0,1 1,1 2),(2 3,3 2,5 4))</para>
- </listitem>
-
- <listitem>
- <para>MULTIPOLYGON(((0 0,4 0,4 4,0 4,0 0),(1 1,2 1,2 2,1 2,1 1)),
- ((-1 -1,-1 -2,-2 -2,-2 -1,-1 -1)))</para>
- </listitem>
-
- <listitem>
- <para>GEOMETRYCOLLECTION(POINT(2 3),LINESTRING(2 3,3 4))</para>
- </listitem>
- </itemizedlist>
-
- <para>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.</para>
-
- <para>Input/Output of these formats are available using the following
- interfaces:</para>
-
- <programlisting>bytea WKB = asBinary(geometry);
-text WKT = asText(geometry);
-geometry = GeomFromWKB(bytea WKB, SRID);
-geometry = GeometryFromText(text WKT, SRID);</programlisting>
-
- <para>For example, a valid insert statement to create and insert an
- OGC spatial object would be:</para>
-
- <programlisting>INSERT INTO geotable ( the_geom, the_name )
- VALUES ( GeomFromText('POINT(-126.4 45.32)', 312), 'A Place');</programlisting>
- </sect2>
-
- <sect2>
- <title>PostGIS EWKB, EWKT and Canonical Forms</title>
-
- <para>OGC formats only support 2d geometries, and the associated SRID
- is *never* embedded in the input/output representations.</para>
-
- <para>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!</para>
-
- <para>PostGIS EWKB/EWKT add 3dm,3dz,4d coordinates support and
- embedded SRID information.</para>
-
- <para>Examples of the text representations (EWKT) of the extended
- spatial objects of the features are as follows:</para>
-
- <itemizedlist>
- <listitem>
- <para>POINT(0 0 0) -- XYZ</para>
- </listitem>
-
- <listitem>
- <para>SRID=32632;POINT(0 0) -- XY with SRID</para>
- </listitem>
-
- <listitem>
- <para>POINTM(0 0 0) -- XYM</para>
- </listitem>
-
- <listitem>
- <para>POINT(0 0 0 0) -- XYZM</para>
- </listitem>
-
- <listitem>
- <para>SRID=4326;MULTIPOINTM(0 0 0,1 2 1) -- XYM with SRID</para>
- </listitem>
-
- <listitem>
- <para>MULTILINESTRING((0 0 0,1 1 0,1 2 1),(2 3 1,3 2 1,5 4 1))</para>
- </listitem>
-
- <listitem>
- <para>POLYGON((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2 0,1
- 2 0,1 1 0))</para>
- </listitem>
-
- <listitem>
- <para>MULTIPOLYGON(((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2
- 2 0,1 2 0,1 1 0)),((-1 -1 0,-1 -2 0,-2 -2 0,-2 -1 0,-1 -1 0)))</para>
- </listitem>
-
- <listitem>
- <para>GEOMETRYCOLLECTIONM(POINTM(2 3 9), LINESTRINGM(2 3 4, 3 4
- 5))</para>
- </listitem>
- </itemizedlist>
-
- <para>Input/Output of these formats are available using the following
- interfaces:</para>
-
- <programlisting>bytea EWKB = asEWKB(geometry);
-text EWKT = asEWKT(geometry);
-geometry = GeomFromEWKB(bytea EWKB);
-geometry = GeomFromEWKT(text EWKT);</programlisting>
-
- <para>For example, a valid insert statement to create and insert a
- PostGIS spatial object would be:</para>
-
- <programlisting>INSERT INTO geotable ( the_geom, the_name )
- VALUES ( GeomFromEWKT('SRID=312;POINTM(-126.4 45.32 15)'), 'A Place' )</programlisting>
-
- <para>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: <programlisting>- Output
- - binary: EWKB
- ascii: HEXEWKB (EWKB in hex form)
-- Input
- - binary: EWKB
- ascii: HEXEWKB|EWKT </programlisting></para>
-
- <para>For example this statement reads EWKT and returns HEXEWKB in the
- process of canonical ascii input/output:</para>
-
- <programlisting>=# SELECT 'SRID=4;POINT(0 0)'::geometry;
-
-geometry
-----------------------------------------------------
-01010000200400000000000000000000000000000000000000
-(1 row)</programlisting>
- </sect2>
-
- <sect2>
- <title>SQL-MM Part 3</title>
-
- <para>The SQL Multimedia Applications Spatial specification extends
- the simple features for SQL spec by defining a number of circularly
- interpolated curves.</para>
-
- <para>The SQL-MM definitions include 3dm, 3dz and 4d coordinates, but
- do not allow the embedding of SRID information.</para>
-
- <para>The well-known text extensions are not yet fully supported.
- Examples of some simple curved geometries are shown below:</para>
-
- <itemizedlist>
- <listitem>
- <para>CIRCULARSTRING(0 0, 1 1, 1 0)</para>
- </listitem>
-
- <listitem>
- <para>COMPOUNDCURVE(CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1))</para>
- </listitem>
-
- <listitem>
- <para>CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3
- 3, 3 1, 1 1))</para>
- </listitem>
-
- <listitem>
- <para>MULTICURVE((0 0, 5 5),CIRCULARSTRING(4 0, 4 4, 8 4))</para>
- </listitem>
-
- <listitem>
- <para>MULTISURFACE(CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4,
- 0 0),(1 1, 3 3, 3 1, 1 1)),((10 10, 14 12, 11 10, 10 10),(11 11,
- 11.5 11, 11 11.5, 11 11)))</para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>Currently, PostGIS cannot support the use of Compound Curves
- in a Curve Polygon.</para>
- </note>
-
- <note>
- <para>All floating point comparisons within the SQL-MM
- implementation are performed to a specified tolerance, currently
- 1E-8.</para>
- </note>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Using OpenGIS Standards</title>
-
- <para>The OpenGIS "Simple Features Specification for SQL"
- defines standard GIS object types, the functions required to manipulate
- them, and a set of meta-data tables. In order to ensure that meta-data
- remain consistent, operations such as creating and removing a spatial
- column are carried out through special procedures defined by OpenGIS.</para>
-
- <para>There are two OpenGIS meta-data tables: <varname>SPATIAL_REF_SYS</varname>
- and <varname>GEOMETRY_COLUMNS</varname>. The <varname>SPATIAL_REF_SYS</varname>
- table holds the numeric IDs and textual descriptions of coordinate
- systems used in the spatial database.</para>
-
- <sect2>
- <title>The SPATIAL_REF_SYS Table</title>
-
- <para>The <varname>SPATIAL_REF_SYS</varname> table definition is as
- follows:</para>
-
- <programlisting>CREATE TABLE spatial_ref_sys (
- srid INTEGER NOT NULL PRIMARY KEY,
- auth_name VARCHAR(256),
- auth_srid INTEGER,
- srtext VARCHAR(2048),
- proj4text VARCHAR(2048)
-)</programlisting>
-
- <para>The <varname>SPATIAL_REF_SYS</varname> columns are as follows:</para>
-
- <variablelist>
- <varlistentry>
- <term>SRID</term>
-
- <listitem>
- <para>An integer value that uniquely identifies the Spatial
- Referencing System (SRS) within the database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>AUTH_NAME</term>
-
- <listitem>
- <para>The name of the standard or standards body that is being
- cited for this reference system. For example, "EPSG"
- would be a valid <varname>AUTH_NAME</varname>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>AUTH_SRID</term>
-
- <listitem>
- <para>The ID of the Spatial Reference System as defined by the
- Authority cited in the <varname>AUTH_NAME</varname>. In the case
- of EPSG, this is where the EPSG projection code would go.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SRTEXT</term>
-
- <listitem>
- <para>The Well-Known Text representation of the Spatial
- Reference System. An example of a WKT SRS representation is:</para>
-
- <programlisting>PROJCS["NAD83 / UTM Zone 10N",
- GEOGCS["NAD83",
- DATUM["North_American_Datum_1983",
- SPHEROID["GRS 1980",6378137,298.257222101]
- ],
- PRIMEM["Greenwich",0],
- UNIT["degree",0.0174532925199433]
- ],
- PROJECTION["Transverse_Mercator"],
- PARAMETER["latitude_of_origin",0],
- PARAMETER["central_meridian",-123],
- PARAMETER["scale_factor",0.9996],
- PARAMETER["false_easting",500000],
- PARAMETER["false_northing",0],
- UNIT["metre",1]
-]</programlisting>
-
- <para>For a listing of EPSG projection codes and their
- corresponding WKT representations, see <ulink
- url="http://www.opengis.org/techno/interop/EPSG2WKT.TXT">http://www.opengis.org/techno/interop/EPSG2WKT.TXT</ulink>.
- For a discussion of WKT in general, see the OpenGIS
- "Coordinate Transformation Services Implementation
- Specification" at <ulink
- url="http://www.opengis.org/techno/specs.htm">http://www.opengis.org/techno/specs.htm</ulink>.
- For information on the European Petroleum Survey Group (EPSG)
- and their database of spatial reference systems, see <ulink
- url="http://epsg.org">http://epsg.org</ulink>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>PROJ4TEXT</term>
-
- <listitem>
- <para>PostGIS uses the Proj4 library to provide coordinate
- transformation capabilities. The <varname>PROJ4TEXT</varname>
- column contains the Proj4 coordinate definition string for a
- particular SRID. For example:</para>
-
- <programlisting>+proj=utm +zone=10 +ellps=clrk66 +datum=NAD27 +units=m</programlisting>
-
- <para>For more information about, see the Proj4 web site at
- <ulink url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.
- The <filename>spatial_ref_sys.sql</filename> file contains both
- <varname>SRTEXT</varname> and <varname>PROJ4TEXT</varname>
- definitions for all EPSG projections.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>The GEOMETRY_COLUMNS Table</title>
-
- <para>The <varname>GEOMETRY_COLUMNS</varname> table definition is as
- follows:</para>
-
- <programlisting>CREATE TABLE geometry_columns (
- f_table_catalog VARRCHAR(256) NOT NULL,
- f_table_schema VARCHAR(256) NOT NULL,
- f_table_nam VARCHAR(256) NOT NULL,
- f_geometry_column VARCHAR(256) NOT NULL,
- coord_dimension INTEGER NOT NULL,
- srid INTEGER NOT NULL,
- type VARCHAR(30) NOT NULL
-)</programlisting>
-
- <para>The columns are as follows:</para>
-
- <variablelist>
- <varlistentry>
- <term>F_TABLE_CATALOG, F_TABLE_SCHEMA, F_TABLE_NAME</term>
-
- <listitem>
- <para>The fully qualified name of the feature table containing
- the geometry column. Note that the terms "catalog" and
- "schema" are Oracle-ish. There is not PostgreSQL
- analogue of "catalog" so that column is left blank --
- for "schema" the PostgreSQL schema name is used (<varname>public</varname>
- is the default).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>F_GEOMETRY_COLUMN</term>
-
- <listitem>
- <para>The name of the geometry column in the feature table.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>COORD_DIMENSION</term>
-
- <listitem>
- <para>The spatial dimension (2, 3 or 4 dimensional) of the
- column.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SRID</term>
-
- <listitem>
- <para>The ID of the spatial reference system used for the
- coordinate geometry in this table. It is a foreign key reference
- to the <varname>SPATIAL_REF_SYS</varname>.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>TYPE</term>
-
- <listitem>
- <para>The type of the spatial object. To restrict the spatial
- column to a single type, use one of: POINT, LINESTRING, POLYGON,
- MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION or
- corresponding XYM versions POINTM, LINESTRINGM, POLYGONM,
- MULTIPOINTM, MULTILINESTRINGM, MULTIPOLYGONM,
- GEOMETRYCOLLECTIONM. For heterogeneous (mixed-type) collections,
- you can use "GEOMETRY" as the type.</para>
-
- <note>
- <para>This attribute is (probably) not part of the OpenGIS
- specification, but is required for ensuring type homogeneity.</para>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Creating a Spatial Table</title>
-
- <para>Creating a table with spatial data is done in two stages:</para>
-
- <itemizedlist>
- <listitem>
- <para>Create a normal non-spatial table.</para>
-
- <para>For example: <command>CREATE TABLE ROADS_GEOM ( ID int4,
- NAME varchar(25) )</command></para>
- </listitem>
-
- <listitem>
- <para>Add a spatial column to the table using the OpenGIS
- "AddGeometryColumn" function.</para>
-
- <para>The syntax is: <programlisting>AddGeometryColumn(
- <schema_name>,
- <table_name>,
- <column_name>,
- <srid>,
- <type>,
- <dimension>
-)</programlisting> Or, using
- current schema: <programlisting>AddGeometryColumn(
- <table_name>,
- <column_name>,
- <srid>,
- <type>,
- <dimension>
-)</programlisting></para>
-
- <para>Example1: <command>SELECT
- AddGeometryColumn('public', 'roads_geom',
- 'geom', 423, 'LINESTRING', 2)</command></para>
-
- <para>Example2: <command>SELECT AddGeometryColumn(
- 'roads_geom', 'geom', 423, 'LINESTRING',
- 2)</command></para>
- </listitem>
- </itemizedlist>
-
- <para>Here is an example of SQL used to create a table and add a
- spatial column (assuming that an SRID of 128 exists already):</para>
-
- <programlisting>CREATE TABLE parks (
- park_id INTEGER,
- park_name VARCHAR,
- park_date DATE,
- park_type VARCHAR
-);
-SELECT AddGeometryColumn('parks', 'park_geom', 128, 'MULTIPOLYGON', 2 );</programlisting>
-
- <para>Here is another example, using the generic "geometry"
- type and the undefined SRID value of -1:</para>
-
- <programlisting>CREATE TABLE roads (
- road_id INTEGER,
- road_name VARCHAR
-);
-SELECT AddGeometryColumn( 'roads', 'roads_geom', -1, 'GEOMETRY', 3 );</programlisting>
- </sect2>
-
- <sect2>
- <title>Ensuring OpenGIS compliancy of geometries</title>
-
- <para>Most of the functions implemented by the GEOS library rely on
- the assumption that your geometries are valid as specified by the
- OpenGIS Simple Feature Specification. To check validity of geometries
- you can use the <link linkend="IsValid">IsValid()</link> function:</para>
-
- <programlisting> gisdb=# select isvalid('LINESTRING(0 0, 1 1)'),
- isvalid('LINESTRING(0 0,0 0)');
-
- isvalid | isvalid
----------+---------
- t | f</programlisting>
-
- <para>By default, PostGIS does not apply this validity check on
- geometry input, because testing for validity needs lots of CPU time
- for complex geometries, especially polygons. If you do not trust your
- data sources, you can manually enforce such a check to your tables by
- adding a check constraint:</para>
-
- <programlisting>ALTER TABLE mytable
- ADD CONSTRAINT geometry_valid_check
- CHECK (isvalid(the_geom));</programlisting>
-
- <para>If you encounter any strange error messages such as "GEOS
- Intersection() threw an error!" or "JTS Intersection() threw
- an error!" when calling PostGIS functions with valid input
- geometries, you likely found an error in either PostGIS or one of the
- libraries it uses, and you should contact the PostGIS developers. The
- same is true if a PostGIS function returns an invalid geometry for
- valid input.</para>
-
- <note>
- <para>Strictly compliant OGC geometries cannot have Z or M values.
- The <link linkend="IsValid">IsValid()</link> function won't
- consider higher dimensioned geometries invalid! Invocations of <link
- linkend="AddGeometryColumn">AddGeometryColumn()</link> will add a
- constraint checking geometry dimensions, so it is enough to specify
- 2 there.</para>
- </note>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Loading GIS Data</title>
-
- <para>Once you have created a spatial table, you are ready to upload GIS
- data to the database. Currently, there are two ways to get data into a
- PostGIS/PostgreSQL database: using formatted SQL statements or using the
- Shape file loader/dumper.</para>
-
- <sect2>
- <title>Using SQL</title>
-
- <para>If you can convert your data to a text representation, then
- using formatted SQL might be the easiest way to get your data into
- PostGIS. As with Oracle and other SQL databases, data can be bulk
- loaded by piping a large text file full of SQL "INSERT"
- statements into the SQL terminal monitor.</para>
-
- <para>A data upload file (<filename>roads.sql</filename> for example)
- might look like this:</para>
-
- <programlisting>BEGIN;
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (1,GeomFromText('LINESTRING(191232 243118,191108 243242)',-1),'Jeff Rd');
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (2,GeomFromText('LINESTRING(189141 244158,189265 244817)',-1),'Geordie Rd');
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (3,GeomFromText('LINESTRING(192783 228138,192612 229814)',-1),'Paul St');
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (4,GeomFromText('LINESTRING(189412 252431,189631 259122)',-1),'Graeme Ave');
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (5,GeomFromText('LINESTRING(190131 224148,190871 228134)',-1),'Phil Tce');
-INSERT INTO roads (road_id, roads_geom, road_name)
- VALUES (6,GeomFromText('LINESTRING(198231 263418,198213 268322)',-1),'Dave Cres');
-COMMIT;</programlisting>
-
- <para>The data file can be piped into PostgreSQL very easily using the
- "psql" SQL terminal monitor:</para>
-
- <programlisting>psql -d [database] -f roads.sql</programlisting>
- </sect2>
-
- <sect2>
- <title>Using the Loader</title>
-
- <para>The <filename>shp2pgsql</filename> data loader converts ESRI
- Shape files into SQL suitable for insertion into a PostGIS/PostgreSQL
- database. The loader has several operating modes distinguished by
- command line flags:</para>
-
- <variablelist>
- <varlistentry>
- <term>-d</term>
-
- <listitem>
- <para>Drops the database table before creating a new table with
- the data in the Shape file.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-a</term>
-
- <listitem>
- <para>Appends data from the Shape file into the database table.
- Note that to use this option to load multiple files, the files
- must have the same attributes and same data types.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-c</term>
-
- <listitem>
- <para>Creates a new table and populates it from the Shape file.
- <emphasis>This is the default mode.</emphasis></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-p</term>
-
- <listitem>
- <para>Only produces the table creation SQL code, without adding
- any actual data. This can be used if you need to completely
- separate the table creation and data loading steps.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-D</term>
-
- <listitem>
- <para>Use the PostgreSQL "dump" format for the output
- data. This can be combined with -a, -c and -d. It is much faster
- to load than the default "insert" SQL format. Use this
- for very large data sets.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-s <SRID></term>
-
- <listitem>
- <para>Creates and populates the geometry tables with the
- specified SRID.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-k</term>
-
- <listitem>
- <para>Keep identifiers' case (column, schema and
- attributes). Note that attributes in Shapefile are all
- UPPERCASE.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-i</term>
-
- <listitem>
- <para>Coerce all integers to standard 32-bit integers, do not
- create 64-bit bigints, even if the DBF header signature appears
- to warrant it.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-I</term>
-
- <listitem>
- <para>Create a GiST index on the geometry column.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-w</term>
-
- <listitem>
- <para>Output WKT format, for use with older (0.x) versions of
- PostGIS. Note that this will introduce coordinate drifts and
- will drop M values from shapefiles.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-W <encoding></term>
-
- <listitem>
- <para>Specify encoding of the input data (dbf file). When used,
- all attributes of the dbf are converted from the specified
- encoding to UTF8. The resulting SQL output will contain a
- <code>SET CLIENT_ENCODING to UTF8</code> command, so that the
- backend will be able to reconvert from UTF8 to whatever encoding
- the database is configured to use internally.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Note that -a, -c, -d and -p are mutually exclusive.</para>
-
- <para>An example session using the loader to create an input file and
- uploading it might look like this:</para>
-
- <programlisting># shp2pgsql shaperoads myschema.roadstable > roads.sql
-# psql -d roadsdb -f roads.sql</programlisting>
-
- <para>A conversion and upload can be done all in one step using UNIX
- pipes:</para>
-
- <programlisting># shp2pgsql shaperoads myschema.roadstable | psql -d roadsdb</programlisting>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Retrieving GIS Data</title>
-
- <para>Data can be extracted from the database using either SQL or the
- Shape file loader/dumper. In the section on SQL we will discuss some of
- the operators available to do comparisons and queries on spatial tables.</para>
-
- <sect2>
- <title>Using SQL</title>
-
- <para>The most straightforward means of pulling data out of the
- database is to use a SQL select query and dump the resulting columns
- into a parsable text file:</para>
-
- <programlisting>db=# SELECT road_id, AsText(road_geom) AS geom, road_name FROM roads;
-
-road_id | geom | road_name
---------+-----------------------------------------+-----------
- 1 | LINESTRING(191232 243118,191108 243242) | Jeff Rd
- 2 | LINESTRING(189141 244158,189265 244817) | Geordie Rd
- 3 | LINESTRING(192783 228138,192612 229814) | Paul St
- 4 | LINESTRING(189412 252431,189631 259122) | Graeme Ave
- 5 | LINESTRING(190131 224148,190871 228134) | Phil Tce
- 6 | LINESTRING(198231 263418,198213 268322) | Dave Cres
- 7 | LINESTRING(218421 284121,224123 241231) | Chris Way
-(6 rows)</programlisting>
-
- <para>However, there will be times when some kind of restriction is
- necessary to cut down the number of fields returned. In the case of
- attribute-based restrictions, just use the same SQL syntax as normal
- with a non-spatial table. In the case of spatial restrictions, the
- following operators are available/useful:</para>
-
- <variablelist>
- <varlistentry>
- <term>&&</term>
-
- <listitem>
- <para>This operator tells whether the bounding box of one
- geometry intersects the bounding box of another.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>~=</term>
-
- <listitem>
- <para>This operators tests whether two geometries are
- geometrically identical. For example, if 'POLYGON((0 0,1 1,1
- 0,0 0))' is the same as 'POLYGON((0 0,1 1,1 0,0 0))'
- (it is).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>=</term>
-
- <listitem>
- <para>This operator is a little more naive, it only tests
- whether the bounding boxes of to geometries are the same.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>Next, you can use these operators in queries. Note that when
- specifying geometries and boxes on the SQL command line, you must
- explicitly turn the string representations into geometries by using
- the "GeomFromText()" function. So, for example:</para>
-
- <programlisting>SELECT road_id, road_name
- FROM roads
- WHERE roads_geom ~= GeomFromText('LINESTRING(191232 243118,191108 243242)',-1);</programlisting>
-
- <para>The above query would return the single record from the
- "ROADS_GEOM" table in which the geometry was equal to that
- value.</para>
-
- <para>When using the "&&" operator, you can specify
- either a BOX3D as the comparison feature or a GEOMETRY. When you
- specify a GEOMETRY, however, its bounding box will be used for the
- comparison.</para>
-
- <programlisting>SELECT road_id, road_name
-FROM roads
-WHERE roads_geom && GeomFromText('POLYGON((...))',-1);</programlisting>
-
- <para>The above query will use the bounding box of the polygon for
- comparison purposes.</para>
-
- <para>The most common spatial query will probably be a
- "frame-based" query, used by client software, like data
- browsers and web mappers, to grab a "map frame" worth of data
- for display. Using a "BOX3D" object for the frame, such a
- query looks like this:</para>
-
- <programlisting>SELECT AsText(roads_geom) AS geom
-FROM roads
-WHERE
- roads_geom && SetSRID('BOX3D(191232 243117,191232 243119)'::box3d,-1);</programlisting>
-
- <para>Note the use of the SRID, to specify the projection of the
- BOX3D. The value -1 is used to indicate no specified SRID.</para>
- </sect2>
-
- <sect2>
- <title>Using the Dumper</title>
-
- <para>The <filename>pgsql2shp</filename> table dumper connects
- directly to the database and converts a table (possibly defined by a
- query) into a shape file. The basic syntax is:</para>
-
- <programlisting>pgsql2shp [<options>] <database> [<schema>.]<table></programlisting>
-
- <programlisting>pgsql2shp [<options>] <database> <query></programlisting>
-
- <para>The commandline options are:</para>
-
- <variablelist>
- <varlistentry>
- <term>-f <filename></term>
-
- <listitem>
- <para>Write the output to a particular filename.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-h <host></term>
-
- <listitem>
- <para>The database host to connect to.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-p <port></term>
-
- <listitem>
- <para>The port to connect to on the database host.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-P <password></term>
-
- <listitem>
- <para>The password to use when connecting to the database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-u <user></term>
-
- <listitem>
- <para>The username to use when connecting to the database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-g <geometry column></term>
-
- <listitem>
- <para>In the case of tables with multiple geometry columns, the
- geometry column to use when writing the shape file.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-b</term>
-
- <listitem>
- <para>Use a binary cursor. This will make the operation faster,
- but will not work if any NON-geometry attribute in the table
- lacks a cast to text.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-r</term>
-
- <listitem>
- <para>Raw mode. Do not drop the <varname>gid</varname> field, or
- escape column names.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>-d</term>
-
- <listitem>
- <para>For backward compatibility: write a 3-dimensional shape
- file when dumping from old (pre-1.0.0) postgis databases (the
- default is to write a 2-dimensional shape file in that case).
- Starting from postgis-1.0.0+, dimensions are fully encoded.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Building Indexes</title>
-
- <para>Indexes are what make using a spatial database for large data sets
- possible. Without indexing, any search for a feature would require a
- "sequential scan" of every record in the database. Indexing
- speeds up searching by organizing the data into a search tree which can
- be quickly traversed to find a particular record. PostgreSQL supports
- three kinds of indexes by default: B-Tree indexes, R-Tree indexes, and
- GiST indexes.</para>
-
- <itemizedlist>
- <listitem>
- <para>B-Trees are used for data which can be sorted along one axis;
- for example, numbers, letters, dates. GIS data cannot be rationally
- sorted along one axis (which is greater, (0,0) or (0,1) or (1,0)?)
- so B-Tree indexing is of no use for us.</para>
- </listitem>
-
- <listitem>
- <para>R-Trees break up data into rectangles, and sub-rectangles, and
- sub-sub rectangles, etc. R-Trees are used by some spatial databases
- to index GIS data, but the PostgreSQL R-Tree implementation is not
- as robust as the GiST implementation.</para>
- </listitem>
-
- <listitem>
- <para>GiST (Generalized Search Trees) indexes break up data into
- "things to one side", "things which overlap",
- "things which are inside" and can be used on a wide range of
- data-types, including GIS data. PostGIS uses an R-Tree index
- implemented on top of GiST to index GIS data.</para>
- </listitem>
- </itemizedlist>
-
- <sect2>
- <title>GiST Indexes</title>
-
- <para>GiST stands for "Generalized Search Tree" and is a
- generic form of indexing. In addition to GIS indexing, GiST is used to
- speed up searches on all kinds of irregular data structures (integer
- arrays, spectral data, etc) which are not amenable to normal B-Tree
- indexing.</para>
-
- <para>Once a GIS data table exceeds a few thousand rows, you will want
- to build an index to speed up spatial searches of the data (unless all
- your searches are based on attributes, in which case you'll want
- to build a normal index on the attribute fields).</para>
-
- <para>The syntax for building a GiST index on a "geometry"
- column is as follows:</para>
-
- <para><programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometryfield] ); </programlisting></para>
-
- <para>Building a spatial index is a computationally intensive
- exercise: on tables of around 1 million rows, on a 300MHz Solaris
- machine, we have found building a GiST index takes about 1 hour. After
- building an index, it is important to force PostgreSQL to collect
- table statistics, which are used to optimize query plans:</para>
-
- <para><programlisting>VACUUM ANALYZE [table_name] [column_name];
--- This is only needed for PostgreSQL 7.4 installations and below
-SELECT UPDATE_GEOMETRY_STATS([table_name], [column_name]);</programlisting></para>
-
- <para>GiST indexes have two advantages over R-Tree indexes in
- PostgreSQL. Firstly, GiST indexes are "null safe", meaning
- they can index columns which include null values. Secondly, GiST
- indexes support the concept of "lossiness" which is important
- when dealing with GIS objects larger than the PostgreSQL 8K page size.
- Lossiness allows PostgreSQL to store only the "important" part
- of an object in an index -- in the case of GIS objects, just the
- bounding box. GIS objects larger than 8K will cause R-Tree indexes to
- fail in the process of being built.</para>
- </sect2>
-
- <sect2>
- <title>Using Indexes</title>
-
- <para>Ordinarily, indexes invisibly speed up data access: once the
- index is built, the query planner transparently decides when to use
- index information to speed up a query plan. Unfortunately, the
- PostgreSQL query planner does not optimize the use of GiST indexes
- well, so sometimes searches which should use a spatial index instead
- default to a sequence scan of the whole table.</para>
-
- <para>If you find your spatial indexes are not being used (or your
- attribute indexes, for that matter) there are a couple things you can
- do:</para>
-
- <itemizedlist>
- <listitem>
- <para>Firstly, make sure statistics are gathered about the number
- and distributions of values in a table, to provide the query
- planner with better information to make decisions around index
- usage. For PostgreSQL 7.4 installations and below this is done by
- running <command>update_geometry_stats([table_name, column_name])</command>
- (compute distribution) and <command>VACUUM ANALYZE [table_name]
- [column_name]</command> (compute number of values). Starting with
- PostgreSQL 8.0 running <command>VACUUM ANALYZE</command> will do
- both operations. You should regularly vacuum your databases
- anyways -- many PostgreSQL DBAs have <command>VACUUM</command> run
- as an off-peak cron job on a regular basis.</para>
- </listitem>
-
- <listitem>
- <para>If vacuuming does not work, you can force the planner to use
- the index information by using the <command>SET ENABLE_SEQSCAN=OFF</command>
- command. You should only use this command sparingly, and only on
- spatially indexed queries: generally speaking, the planner knows
- better than you do about when to use normal B-Tree indexes. Once
- you have run your query, you should consider setting
- <varname>ENABLE_SEQSCAN</varname> back on, so that other queries
- will utilize the planner as normal.</para>
-
- <note>
- <para>As of version 0.6, it should not be necessary to force the
- planner to use the index with <varname>ENABLE_SEQSCAN</varname>.</para>
- </note>
- </listitem>
-
- <listitem>
- <para>If you find the planner wrong about the cost of sequential
- vs index scans try reducing the value of random_page_cost in
- postgresql.conf or using SET random_page_cost=#. Default value for
- the parameter is 4, try setting it to 1 or 2. Decrementing the
- value makes the planner more inclined of using Index scans.</para>
- </listitem>
- </itemizedlist>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Complex Queries</title>
-
- <para>The <emphasis>raison d'etre</emphasis> of spatial database
- functionality is performing queries inside the database which would
- ordinarily require desktop GIS functionality. Using PostGIS effectively
- requires knowing what spatial functions are available, and ensuring that
- appropriate indexes are in place to provide good performance.</para>
-
- <sect2>
- <title>Taking Advantage of Indexes</title>
-
- <para>When constructing a query it is important to remember that only
- the bounding-box-based operators such as && can take advantage
- of the GiST spatial index. Functions such as <varname>distance()</varname>
- cannot use the index to optimize their operation. For example, the
- following query would be quite slow on a large table:</para>
-
- <programlisting>SELECT the_geom
-FROM geom_table
-WHERE ST_Distance(the_geom, GeomFromText('POINT(100000 200000)', -1)) < 100</programlisting>
-
- <para>This query is selecting all the geometries in geom_table which
- are within 100 units of the point (100000, 200000). It will be slow
- because it is calculating the distance between each point in the table
- and our specified point, ie. one <varname>ST_Distance()</varname>
- calculation for each row in the table. We can avoid this by using the
- && operator to reduce the number of distance calculations
- required:</para>
-
- <programlisting>SELECT the_geom
-FROM geom_table
-WHERE the_geom && 'BOX3D(90900 190900, 100100 200100)'::box3d
- AND
-ST_Distance(the_geom, GeomFromText('POINT(100000 200000)', -1)) < 100</programlisting>
-
- <para>This query selects the same geometries, but it does it in a more
- efficient way. Assuming there is a GiST index on the_geom, the query
- planner will recognize that it can use the index to reduce the number
- of rows before calculating the result of the <varname>distance()</varname>
- function. Notice that the <varname>BOX3D</varname> geometry which is
- used in the && operation is a 200 unit square box centered on
- the original point - this is our "query box". The &&
- operator uses the index to quickly reduce the result set down to only
- those geometries which have bounding boxes that overlap the "query
- box". Assuming that our query box is much smaller than the extents
- of the entire geometry table, this will drastically reduce the number
- of distance calculations that need to be done.</para>
-
- <note><title>Change in Behavior</title>
- <para>As of PostGIS 1.3.0, most of the Geometry
- Relationship Functions, with the notable exceptions of ST_Disjoint and
- ST_Relate, include implicit bounding box overlap operators.</para></note>
- </sect2>
-
- <sect2>
- <title>Examples of Spatial SQL</title>
-
- <para>The examples in this section will make use of two tables, a
- table of linear roads, and a table of polygonal municipality
- boundaries. The table definitions for the <varname>bc_roads</varname>
- table is:</para>
-
- <programlisting>Column | Type | Description
-------------+-------------------+-------------------
-gid | integer | Unique ID
-name | character varying | Road Name
-the_geom | geometry | Location Geometry (Linestring)</programlisting>
-
- <para>The table definition for the <varname>bc_municipality</varname>
- table is:</para>
-
- <programlisting>Column | Type | Description
------------+-------------------+-------------------
-gid | integer | Unique ID
-code | integer | Unique ID
-name | character varying | City / Town Name
-the_geom | geometry | Location Geometry (Polygon)</programlisting>
-
- <qandaset>
- <qandaentry>
- <question>
- <para>What is the total length of all roads, expressed in
- kilometers?</para>
- </question>
-
- <answer>
- <para>You can answer this question with a very simple piece of
- SQL:</para>
-
- <programlisting>SELECT sum(ST_Length(the_geom))/1000 AS km_roads FROM bc_roads;
-
-km_roads
-------------------
-70842.1243039643
-(1 row)</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>How large is the city of Prince George, in hectares?</para>
- </question>
-
- <answer>
- <para>This query combines an attribute condition (on the
- municipality name) with a spatial calculation (of the area):</para>
-
- <programlisting>SELECT
- ST_Area(the_geom)/10000 AS hectares
-FROM bc_municipality
-WHERE name = 'PRINCE GEORGE';
-
-hectares
-------------------
-32657.9103824927
-(1 row)</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What is the largest municipality in the province, by area?</para>
- </question>
-
- <answer>
- <para>This query brings a spatial measurement into the query
- condition. There are several ways of approaching this problem,
- but the most efficient is below:</para>
-
- <programlisting>SELECT
- name,
- ST_Area(the_geom)/10000 AS hectares
-FROM
- bc_municipality
-ORDER BY hectares DESC
-LIMIT 1;
-
-name | hectares
----------------+-----------------
-TUMBLER RIDGE | 155020.02556131
-(1 row)</programlisting>
-
- <para>Note that in order to answer this query we have to
- calculate the area of every polygon. If we were doing this a lot
- it would make sense to add an area column to the table that we
- could separately index for performance. By ordering the results
- in a descending direction, and them using the PostgreSQL
- "LIMIT" command we can easily pick off the largest value
- without using an aggregate function like max().</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What is the length of roads fully contained within each
- municipality?</para>
- </question>
-
- <answer>
- <para>This is an example of a "spatial join", because we
- are bringing together data from two tables (doing a join) but
- using a spatial interaction condition ("contained") as
- the join condition rather than the usual relational approach of
- joining on a common key:</para>
-
- <programlisting>SELECT
- m.name,
- sum(ST_Length(r.the_geom))/1000 as roads_km
-FROM
- bc_roads AS r,
- bc_municipality AS m
-WHERE
- ST_Contains(m.the_geom,r.the_geom)
-GROUP BY m.name
-ORDER BY roads_km;
-
-name | roads_km
-----------------------------+------------------
-SURREY | 1539.47553551242
-VANCOUVER | 1450.33093486576
-LANGLEY DISTRICT | 833.793392535662
-BURNABY | 773.769091404338
-PRINCE GEORGE | 694.37554369147
-...</programlisting>
-
- <para>This query takes a while, because every road in the table
- is summarized into the final result (about 250K roads for our
- particular example table). For smaller overlays (several
- thousand records on several hundred) the response can be very
- fast.</para>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>Create a new table with all the roads within the city of
- Prince George.</para>
- </question>
-
- <answer>
- <para>This is an example of an "overlay", which takes in
- two tables and outputs a new table that consists of spatially
- clipped or cut resultants. Unlike the "spatial join"
- demonstrated above, this query actually creates new geometries.
- An overlay is like a turbo-charged spatial join, and is useful
- for more exact analysis work:</para>
-
- <programlisting>CREATE TABLE pg_roads as
-SELECT
- ST_Intersection(r.the_geom, m.the_geom) AS intersection_geom,
- ST_Length(r.the_geom) AS rd_orig_length,
- r.*
-FROM
- bc_roads AS r,
- bc_municipality AS m
-WHERE m.name = 'PRINCE GEORGE' AND ST_Intersects(r.the_geom, m.the_geom);</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What is the length in kilometers of "Douglas St"
- in Victoria?</para>
- </question>
-
- <answer>
- <programlisting>SELECT
- sum(ST_Length(r.the_geom))/1000 AS kilometers
-FROM
- bc_roads r,
- bc_municipality m
-WHERE r.name = 'Douglas St' AND m.name = 'VICTORIA'
- AND ST_Contains(m.the_geom, r.the_geom) ;
-
-kilometers
-------------------
-4.89151904172838
-(1 row)</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>What is the largest municipality polygon that has a hole?</para>
- </question>
-
- <answer>
- <programlisting>SELECT gid, name, ST_Area(the_geom) AS area
-FROM bc_municipality
-WHERE ST_NRings(the_geom) > 1
-ORDER BY area DESC LIMIT 1;
-
-gid | name | area
------+--------------+------------------
-12 | SPALLUMCHEEN | 257374619.430216
-(1 row)</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Using Mapserver</title>
-
- <para>The Minnesota Mapserver is an internet web-mapping server which
- conforms to the OpenGIS Web Mapping Server specification.</para>
-
- <itemizedlist>
- <listitem>
- <para>The Mapserver homepage is at <ulink
- url="http://mapserver.gis.umn.edu">http://mapserver.gis.umn.edu</ulink>.</para>
- </listitem>
-
- <listitem>
- <para>The OpenGIS Web Map Specification is at <ulink
- url="http://www.opengis.org/techno/specs/01-047r2.pdf">http://www.opengis.org/techno/specs/01-047r2.pdf</ulink>.</para>
- </listitem>
- </itemizedlist>
-
- <sect2>
- <title>Basic Usage</title>
-
- <para>To use PostGIS with Mapserver, you will need to know about how
- to configure Mapserver, which is beyond the scope of this
- documentation. This section will cover specific PostGIS issues and
- configuration details.</para>
-
- <para>To use PostGIS with Mapserver, you will need:</para>
-
- <itemizedlist>
- <listitem>
- <para>Version 0.6 or newer of PostGIS.</para>
- </listitem>
-
- <listitem>
- <para>Version 3.5 or newer of Mapserver.</para>
- </listitem>
- </itemizedlist>
-
- <para>Mapserver accesses PostGIS/PostgreSQL data like any other
- PostgreSQL client -- using <filename>libpq</filename>. This means that
- Mapserver can be installed on any machine with network access to the
- PostGIS server, as long as the system has the <filename>libpq</filename>
- PostgreSQL client libraries.</para>
-
- <orderedlist>
- <listitem>
- <para>Compile and install Mapserver, with whatever options you
- desire, including the "--with-postgis" configuration
- option.</para>
- </listitem>
-
- <listitem>
- <para>In your Mapserver map file, add a PostGIS layer. For
- example:</para>
-
- <programlisting>LAYER
- CONNECTIONTYPE postgis
- NAME "widehighways"
- # Connect to a remote spatial database
- CONNECTION "user=dbuser dbname=gisdatabase host=bigserver"
- # Get the lines from the 'geom' column of the 'roads' table
- DATA "geom from roads"
- STATUS ON
- TYPE LINE
- # Of the lines in the extents, only render the wide highways
- FILTER "type = 'highway' and numlanes >= 4"
- CLASS
- # Make the superhighways brighter and 2 pixels wide
- EXPRESSION ([numlanes] >= 6)
- COLOR 255 22 22
- SYMBOL "solid"
- SIZE 2
- END
- CLASS
- # All the rest are darker and only 1 pixel wide
- EXPRESSION ([numlanes] < 6)
- COLOR 205 92 82
- END
-END</programlisting>
-
- <para>In the example above, the PostGIS-specific directives are as
- follows:</para>
-
- <variablelist>
- <varlistentry>
- <term>CONNECTIONTYPE</term>
-
- <listitem>
- <para>For PostGIS layers, this is always "postgis".</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>CONNECTION</term>
-
- <listitem>
- <para>The database connection is governed by the a
- 'connection string' which is a standard set of keys
- and values like this (with the default values in
- <>):</para>
-
- <para>user=<username> password=<password>
- dbname=<username> hostname=<server>
- port=<5432></para>
-
- <para>An empty connection string is still valid, and any of
- the key/value pairs can be omitted. At a minimum you will
- generally supply the database name and username to connect
- with.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DATA</term>
-
- <listitem>
- <para>The form of this parameter is "<column>
- from <tablename>" where the column is the
- spatial column to be rendered to the map.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FILTER</term>
-
- <listitem>
- <para>The filter must be a valid SQL string corresponding to
- the logic normally following the "WHERE" keyword in
- a SQL query. So, for example, to render only roads with 6 or
- more lanes, use a filter of "num_lanes >= 6".</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
-
- <listitem>
- <para>In your spatial database, ensure you have spatial (GiST)
- indexes built for any the layers you will be drawing.</para>
-
- <programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometrycolumn] );</programlisting>
- </listitem>
-
- <listitem>
- <para>If you will be querying your layers using Mapserver you will
- also need an "oid index".</para>
-
- <para>Mapserver requires unique identifiers for each spatial
- record when doing queries, and the PostGIS module of Mapserver
- uses the PostgreSQL <varname>oid</varname> value to provide these
- unique identifiers. A side-effect of this is that in order to do
- fast random access of records during queries, an index on the
- <varname>oid</varname> is needed.</para>
-
- <para>To build an "oid index", use the following SQL:</para>
-
- <programlisting>CREATE INDEX [indexname] ON [tablename] ( oid );</programlisting>
- </listitem>
- </orderedlist>
- </sect2>
-
- <sect2>
- <title>Frequently Asked Questions</title>
-
- <qandaset>
- <qandaentry>
- <question>
- <para>When I use an <varname>EXPRESSION</varname> in my map
- file, the condition never returns as true, even though I know
- the values exist in my table.</para>
- </question>
-
- <answer>
- <para>Unlike shape files, PostGIS field names have to be
- referenced in EXPRESSIONS using <emphasis>lower case</emphasis>.</para>
-
- <programlisting>EXPRESSION ([numlanes] >= 6)</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>The FILTER I use for my Shape files is not working for my
- PostGIS table of the same data.</para>
- </question>
-
- <answer>
- <para>Unlike shape files, filters for PostGIS layers use SQL
- syntax (they are appended to the SQL statement the PostGIS
- connector generates for drawing layers in Mapserver).</para>
-
- <programlisting>FILTER "type = 'highway' and numlanes >= 4"</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>My PostGIS layer draws much slower than my Shape file
- layer, is this normal?</para>
- </question>
-
- <answer>
- <para>In general, expect PostGIS layers to be 10% slower than
- equivalent Shape files layers, due to the extra overhead
- involved in database connections, data transformations and data
- transit between the database and Mapserver.</para>
-
- <para>If you are finding substantial draw performance problems,
- it is likely that you have not build a spatial index on your
- table.</para>
-
- <programlisting>postgis# CREATE INDEX geotable_gix ON geotable USING GIST ( geocolumn );
-postgis# SELECT update_geometry_stats(); -- For PGSQL < 8.0
-postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0</programlisting>
- </answer>
- </qandaentry>
-
- <qandaentry>
- <question>
- <para>My PostGIS layer draws fine, but queries are really slow.
- What is wrong?</para>
- </question>
-
- <answer>
- <para>For queries to be fast, you must have a unique key for
- your spatial table and you must have an index on that unique
- key.</para>
-
- <para>You can specify what unique key for mapserver to use with
- the <varname>USING UNIQUE</varname> clause in your
- <varname>DATA</varname> line:</para>
-
- <programlisting>DATA "the_geom FROM geotable USING UNIQUE gid"</programlisting>
-
- <para>If your table does not have an explicit unique column, you
- can "fake" a unique column by using the PostgreSQL row
- "oid" for your unique column. "oid" is the
- default unique column if you do not declare one, so enhancing
- your query speed is a matter of building an index on your
- spatial table oid value.</para>
-
- <programlisting>postgis# CREATE INDEX geotable_oid_idx ON geotable (oid);</programlisting>
- </answer>
- </qandaentry>
- </qandaset>
- </sect2>
-
- <sect2>
- <title>Advanced Usage</title>
-
- <para>The <varname>USING</varname> pseudo-SQL clause is used to add
- some information to help mapserver understand the results of more
- complex queries. More specifically, when either a view or a subselect
- is used as the source table (the thing to the right of "FROM"
- in a <varname>DATA</varname> definition) it is more difficult for
- mapserver to automatically determine a unique identifier for each row
- and also the SRID for the table. The <varname>USING</varname> clause
- can provide mapserver with these two pieces of information as follows:</para>
-
- <programlisting>DATA "the_geom FROM (
- SELECT
- table1.the_geom AS the_geom,
- table1.oid AS oid,
- table2.data AS data
- FROM table1
- LEFT JOIN table2
- ON table1.id = table2.id
-) AS new_table USING UNIQUE oid USING SRID=-1"</programlisting>
-
- <variablelist>
- <varlistentry>
- <term>USING UNIQUE <uniqueid></term>
-
- <listitem>
- <para>Mapserver requires a unique id for each row in order to
- identify the row when doing map queries. Normally, it would use
- the oid as the unique identifier, but views and subselects
- don't automatically have an oid column. If you want to use
- Mapserver's query functionality, you need to add a unique
- column to your view or subselect, and declare it with
- <varname>USING UNIQUE</varname>. For example, you could
- explicitly select one of the table's oid values for this
- purpose, or any other column which is guaranteed to be unique
- for the result set.</para>
-
- <para>The <varname>USING</varname> statement can also be useful
- even for simple <varname>DATA</varname> statements, if you are
- doing map queries. It was previously recommended to add an index
- on the oid column of tables used in query-able layers, in order
- to speed up the performance of map queries. However, with the
- <varname>USING</varname> clause, it is possible to tell
- mapserver to use your table's primary key as the identifier
- for map queries, and then it is no longer necessary to have an
- additional index.</para>
-
- <note>
- <para>"Querying a Map" is the action of clicking on a
- map to ask for information about the map features in that
- location. Don't confuse "map queries" with the SQL
- query in a <varname>DATA</varname> definition.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>USING SRID=<srid></term>
-
- <listitem>
- <para>PostGIS needs to know which spatial referencing system is
- being used by the geometries in order to return the correct data
- back to mapserver. Normally it is possible to find this
- information in the "geometry_columns" table in the
- PostGIS database, however, this is not possible for tables which
- are created on the fly such as subselects and views. So the
- <varname>USING SRID=</varname> option allows the correct SRID to
- be specified in the <varname>DATA</varname> definition.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <warning>
- <para>The parser for Mapserver PostGIS layers is fairly primitive,
- and is case sensitive in a few areas. Be careful to ensure that all
- SQL keywords and all your <varname>USING</varname> clauses are in
- upper case, and that your <varname>USING UNIQUE</varname> clause
- precedes your <varname>USING SRID</varname> clause.</para>
- </warning>
- </sect2>
-
- <sect2>
- <title>Examples</title>
-
- <para>Lets start with a simple example and work our way up. Consider
- the following Mapserver layer definition:</para>
-
- <programlisting>LAYER
- CONNECTIONTYPE postgis
- NAME "roads"
- CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
- DATA "the_geom FROM roads"
- STATUS ON
- TYPE LINE
- CLASS
- COLOR 0 0 0
- END
-END</programlisting>
-
- <para>This layer will display all the road geometries in the roads
- table as black lines.</para>
-
- <para>Now lets say we want to show only the highways until we get
- zoomed in to at least a 1:100000 scale - the next two layers will
- achieve this effect:</para>
-
- <programlisting>LAYER
- CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
- DATA "the_geom FROM roads"
- MINSCALE 100000
- STATUS ON
- TYPE LINE
- FILTER "road_type = 'highway'"
- CLASS
- COLOR 0 0 0
- END
-END
-LAYER
- CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
- DATA "the_geom FROM roads"
- MAXSCALE 100000
- STATUS ON
- TYPE LINE
- CLASSITEM road_type
- CLASS
- EXPRESSION "highway"
- SIZE 2
- COLOR 255 0 0
- END
- CLASS
- COLOR 0 0 0
- END
-END</programlisting>
-
- <para>The first layer is used when the scale is greater than 1:100000,
- and displays only the roads of type "highway" as black lines.
- The <varname>FILTER</varname> option causes only roads of type
- "highway" to be displayed.</para>
-
- <para>The second layer is used when the scale is less than 1:100000,
- and will display highways as double-thick red lines, and other roads
- as regular black lines.</para>
-
- <para>So, we have done a couple of interesting things using only
- mapserver functionality, but our <varname>DATA</varname> SQL statement
- has remained simple. Suppose that the name of the road is stored in
- another table (for whatever reason) and we need to do a join to get it
- and label our roads.</para>
-
- <programlisting>LAYER
- CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
- DATA "the_geom FROM (SELECT roads.oid AS oid, roads.the_geom AS the_geom,
- road_names.name as name FROM roads LEFT JOIN road_names ON
- roads.road_name_id = road_names.road_name_id)
- AS named_roads USING UNIQUE oid USING SRID=-1"
- MAXSCALE 20000
- STATUS ON
- TYPE ANNOTATION
- LABELITEM name
- CLASS
- LABEL
- ANGLE auto
- SIZE 8
- COLOR 0 192 0
- TYPE truetype
- FONT arial
- ENDl
- END
-END</programlisting>
-
- <para>This annotation layer adds green labels to all the roads when
- the scale gets down to 1:20000 or less. It also demonstrates how to
- use an SQL join in a <varname>DATA</varname> definition.</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Java Clients (JDBC)</title>
-
- <para>Java clients can access PostGIS "geometry" objects in the
- PostgreSQL database either directly as text representations or using the
- JDBC extension objects bundled with PostGIS. In order to use the
- extension objects, the "postgis.jar" file must be in your
- CLASSPATH along with the "postgresql.jar" JDBC driver package.</para>
-
- <programlisting>import java.sql.*;
-import java.util.*;
-import java.lang.*;
-import org.postgis.*;
-
-public class JavaGIS {
-
-public static void main(String[] args) {
-
- java.sql.Connection conn;
-
- try {
- /*
- * Load the JDBC driver and establish a connection.
- */
- Class.forName("org.postgresql.Driver");
- String url = "jdbc:postgresql://localhost:5432/database";
- conn = DriverManager.getConnection(url, "postgres", "");
- /*
- * Add the geometry types to the connection. Note that you
- * must cast the connection to the pgsql-specific connection
- * implementation before calling the addDataType() method.
- */
- ((org.postgresql.Connection)conn).addDataType("geometry","org.postgis.PGgeometry")
-;
- ((org.postgresql.Connection)conn).addDataType("box3d","org.postgis.PGbox3d");
- /*
- * Create a statement and execute a select query.
- */
- Statement s = conn.createStatement();
- ResultSet r = s.executeQuery("select AsText(geom) as geom,id from geomtable");
- while( r.next() ) {
- /*
- * Retrieve the geometry as an object then cast it to the geometry type.
- * Print things out.
- */
- PGgeometry geom = (PGgeometry)r.getObject(1);
- int id = r.getInt(2);
- System.out.println("Row " + id + ":");
- System.out.println(geom.toString());
- }
- s.close();
- conn.close();
- }
-catch( Exception e ) {
- e.printStackTrace();
- }
-}
-}</programlisting>
-
- <para>The "PGgeometry" object is a wrapper object which contains
- a specific topological geometry object (subclasses of the abstract class
- "Geometry") depending on the type: Point, LineString, Polygon,
- MultiPoint, MultiLineString, MultiPolygon.</para>
-
- <programlisting>PGgeometry geom = (PGgeometry)r.getObject(1);
-if( geom.getType() = Geometry.POLYGON ) {
- Polygon pl = (Polygon)geom.getGeometry();
- for( int r = 0; r < pl.numRings(); r++) {
- LinearRing rng = pl.getRing(r);
- System.out.println("Ring: " + r);
- for( int p = 0; p < rng.numPoints(); p++ ) {
- Point pt = rng.getPoint(p);
- System.out.println("Point: " + p);
- System.out.println(pt.toString());
- }
- }
-}</programlisting>
-
- <para>The JavaDoc for the extension objects provides a reference for the
- various data accessor functions in the geometric objects.</para>
- </sect1>
-
- <sect1>
- <title>C Clients (libpq)</title>
-
- <para>...</para>
-
- <sect2>
- <title>Text Cursors</title>
-
- <para>...</para>
- </sect2>
-
- <sect2>
- <title>Binary Cursors</title>
-
- <para>...</para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Performance tips</title>
-
- <sect1>
- <title>Small tables of large geometries</title>
-
- <sect2>
- <title>Problem description</title>
-
- <para>Current PostgreSQL versions (including 8.0) suffer from a query
- optimizer weakness regarding TOAST tables. TOAST tables are a kind of
- "extension room" used to store large (in the sense of data
- size) values that do not fit into normal data pages (like long texts,
- images or complex geometries with lots of vertices), see
- http://www.postgresql.org/docs/8.0/static/storage-toast.html for more
- information).</para>
-
- <para>The problem appears if you happen to have a table with rather
- large geometries, but not too much rows of them (like a table
- containing the boundaries of all European countries in high
- resolution). Then the table itself is small, but it uses lots of TOAST
- space. In our example case, the table itself had about 80 rows and
- used only 3 data pages, but the TOAST table used 8225 pages.</para>
-
- <para>Now issue a query where you use the geometry operator &&
- to search for a bounding box that matches only very few of those rows.
- Now the query optimizer sees that the table has only 3 pages and 80
- rows. He estimates that a sequential scan on such a small table is
- much faster than using an index. And so he decides to ignore the GIST
- index. Usually, this estimation is correct. But in our case, the
- && operator has to fetch every geometry from disk to compare
- the bounding boxes, thus reading all TOAST pages, too.</para>
-
- <para>To see whether your suffer from this bug, use the "EXPLAIN
- ANALYZE" postgresql command. For more information and the
- technical details, you can read the thread on the postgres performance
- mailing list:
- http://archives.postgresql.org/pgsql-performance/2005-02/msg00030.php</para>
- </sect2>
-
- <sect2>
- <title>Workarounds</title>
-
- <para>The PostgreSQL people are trying to solve this issue by making
- the query estimation TOAST-aware. For now, here are two workarounds:</para>
-
- <para>The first workaround is to force the query planner to use the
- index. Send "SET enable_seqscan TO off;" to the server before
- issuing the query. This basically forces the query planner to avoid
- sequential scans whenever possible. So it uses the GIST index as
- usual. But this flag has to be set on every connection, and it causes
- the query planner to make misestimations in other cases, so you should
- "SET enable_seqscan TO on;" after the query.</para>
-
- <para>The second workaround is to make the sequential scan as fast as
- the query planner thinks. This can be achieved by creating an
- additional column that "caches" the bbox, and matching against
- this. In our example, the commands are like:</para>
-
- <programlisting>SELECT AddGeometryColumn('myschema','mytable','bbox','4326','GEOMETRY','2');
-UPDATE mytable SET bbox = ST_Envelope(ST_Force_2d(the_geom));</programlisting>
-
- <para>Now change your query to use the && operator against
- bbox instead of geom_column, like:</para>
-
- <programlisting>SELECT geom_column
-FROM mytable
-WHERE bbox && ST_SetSRID('BOX3D(0 0,1 1)'::box3d,4326);</programlisting>
-
- <para>Of course, if you change or add rows to mytable, you have to
- keep the bbox "in sync". The most transparent way to do this
- would be triggers, but you also can modify your application to keep
- the bbox column current or run the UPDATE query above after every
- modification.</para>
- </sect2>
- </sect1>
-
- <sect1>
- <title>CLUSTERing on geometry indices</title>
-
- <para>For tables that are mostly read-only, and where a single index is
- used for the majority of queries, PostgreSQL offers the CLUSTER command.
- This command physically reorders all the data rows in the same order as
- the index criteria, yielding two performance advantages: First, for
- index range scans, the number of seeks on the data table is drastically
- reduced. Second, if your working set concentrates to some small
- intervals on the indices, you have a more efficient caching because the
- data rows are spread along fewer data pages. (Feel invited to read the
- CLUSTER command documentation from the PostgreSQL manual at this point.)</para>
-
- <para>However, currently PostgreSQL does not allow clustering on PostGIS
- GIST indices because GIST indices simply ignores NULL values, you get an
- error message like:</para>
-
- <programlisting>lwgeom=# CLUSTER my_geom_index ON my_table;
-ERROR: cannot cluster when index access method does not handle null values
-HINT: You may be able to work around this by marking column "the_geom" NOT NULL.</programlisting>
-
- <para>As the HINT message tells you, one can work around this deficiency
- by adding a "not null" constraint to the table:</para>
-
- <programlisting>lwgeom=# ALTER TABLE my_table ALTER COLUMN the_geom SET not null;
-ALTER TABLE</programlisting>
-
- <para>Of course, this will not work if you in fact need NULL values in
- your geometry column. Additionally, you must use the above method to add
- the constraint, using a CHECK constraint like "ALTER TABLE blubb ADD
- CHECK (geometry is not null);" will not work.</para>
- </sect1>
-
- <sect1>
- <title>Avoiding dimension conversion</title>
-
- <para>Sometimes, you happen to have 3D or 4D data in your table, but
- always access it using OpenGIS compliant ST_AsText() or ST_AsBinary()
- functions that only output 2D geometries. They do this by internally
- calling the ST_Force_2d() function, which introduces a significant overhead
- for large geometries. To avoid this overhead, it may be feasible to
- pre-drop those additional dimensions once and forever:</para>
-
- <programlisting>UPDATE mytable SET the_geom = ST_Force_2d(the_geom);
-VACUUM FULL ANALYZE mytable;</programlisting>
-
- <para>Note that if you added your geometry column using
- AddGeometryColumn() there'll be a constraint on geometry dimension.
- To bypass it you will need to drop the constraint. Remember to update
- the entry in the geometry_columns table and recreate the constraint
- afterwards.</para>
-
- <para>In case of large tables, it may be wise to divide this UPDATE into
- smaller portions by constraining the UPDATE to a part of the table via a
- WHERE clause and your primary key or another feasible criteria, and
- running a simple "VACUUM;" between your UPDATEs. This
- drastically reduces the need for temporary disk space. Additionally, if
- you have mixed dimension geometries, restricting the UPDATE by
- "WHERE dimension(the_geom)>2" skips re-writing of geometries
- that already are in 2D.</para>
- </sect1>
- </chapter>
-
- <chapter>
- <title>PostGIS Reference</title>
-
- <para>The functions given below are the ones which a user of PostGIS is
- likely to need. There are other functions which are required support
- functions to the PostGIS objects which are not of use to a general user.</para>
-
- <note>
- <para>PostGIS has begun a transition from the existing naming convention
- to an SQL-MM-centric convention. As a result, most of the functions that
- you know and love have been renamed using the standard spatial type (ST)
- prefix. Previous functions are still available, though are not listed in
- this document where updated functions are equivalent. These will be
- deprecated in a future release.</para>
- </note>
-
- <sect1>
- <title>OpenGIS Functions</title>
-
- <sect2>
- <title>Management Functions</title>
-
- <variablelist>
- <varlistentry id="AddGeometryColumn">
- <term>AddGeometryColumn(varchar, varchar, varchar, integer,
- varchar, integer)</term>
-
- <listitem>
- <para>Syntax: AddGeometryColumn(<schema_name>,
- <table_name>, <column_name>, <srid>,
- <type>, <dimension>). Adds a geometry column to
- an existing table of attributes. The <varname>schema_name</varname>
- is the name of the table schema (unused for pre-schema
- PostgreSQL installations). The <varname>srid</varname> must be
- an integer value reference to an entry in the SPATIAL_REF_SYS
- table. The <varname>type</varname> must be an uppercase string
- corresponding to the geometry type, eg, 'POLYGON' or
- 'MULTILINESTRING'.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DropGeometryColumn(varchar, varchar, varchar)</term>
-
- <listitem>
- <para>Syntax: DropGeometryColumn(<schema_name>,
- <table_name>, <column_name>). Remove a geometry
- column from a spatial table. Note that schema_name will need to
- match the f_schema_name field of the table's row in the
- geometry_columns table.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SetSRID(geometry, integer)</term>
-
- <listitem>
- <para>Set the SRID on a geometry to a particular integer value.
- Useful in constructing bounding boxes for queries.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Relationship Functions</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_Distance(geometry, geometry)</term>
-
- <listitem>
- <para>Return the cartesian distance between two geometries in
- projected units. Does not use indexes.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_DWithin(geometry, geometry, float)</term>
-
- <listitem>
- <para>Returns true if geometries are within the specified distance
- of one another. Uses indexes if available.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Equals(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the given Geometries are
- "spatially equal". Use this for a 'better'
- answer than '='. equals('LINESTRING(0 0, 10
- 10)','LINESTRING(0 0, 5 5, 10 10)') is true.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>OGC SPEC s2.1.1.2</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Disjoint(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries are "spatially
- disjoint".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 //s2.1.13.3 - a.Relate(b,
- 'FF*FF****')</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Intersects(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries "spatially
- intersect".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Intersects.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 //s2.1.13.3 - Intersects(g1, g2 )
- --> Not (Disjoint(g1, g2 ))</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Touches(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries "spatially
- touch".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Touches.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3- a.Touches(b) -> (I(a)
- intersection I(b) = {empty set} ) and (a intersection b) not
- empty</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Crosses(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries "spatially
- cross".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Crosses.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
- 'T*T******')</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Within(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if Geometry A is "spatially
- within" Geometry B. A has to be completely inside B.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Within.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
- 'T*F**F***')</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Overlaps(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries "spatially
- overlap".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Overlaps.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Contains(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if Geometry A "spatially
- contains" Geometry B.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Contains.</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - same as within(geometry
- B, geometry A)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Covers(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if no point in Geometry B is outside
- Geometry A</para>
- <para>Refer to http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html
- for an explanation of the need of this function.</para>
- <para>This function call will automatically include a bounding box comparison that will make use of any indexes that are available on the geometries. To avoid index use, use the function _ST_Covers.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_CoveredBy(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if no point in Geometry A is outside
- Geometry B</para>
- <para>Refer to http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html
- for an explaination of the need of this function.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Intersects(geometry, geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if the Geometries "spatially
- intersect".</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - NOT disjoint(geometry,
- geometry)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Relate(geometry, geometry, intersectionPatternMatrix)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is spatially related to
- anotherGeometry, by testing for intersections between the
- Interior, Boundary and Exterior of the two geometries as
- specified by the values in the intersectionPatternMatrix.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>NOTE: this is the "allowable" version that returns
- a boolean, not an integer.</para>
-
- <para>OGC SPEC s2.1.1.2 // s2.1.13.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Relate(geometry, geometry)</term>
-
- <listitem>
- <para>returns the DE-9IM (dimensionally extended
- nine-intersection matrix)</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>not in OGC spec, but implied. see s2.1.13.2</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Processing Functions</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_Centroid(geometry)</term>
-
- <listitem>
- <para>Returns the centroid of the geometry as a point.</para>
-
- <para>Computation will be more accurate if performed by the GEOS
- module (enabled at compile time).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Area(geometry)</term>
-
- <listitem>
- <para>Returns the area of the geometry if it is a polygon or
- multi-polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Length(geometry)</term>
-
- <listitem>
- <para>The length of this Curve in its associated spatial
- reference.</para>
-
- <para>synonym for length2d()</para>
-
- <para>OGC SPEC 2.1.5.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointOnSurface(geometry)</term>
-
- <listitem>
- <para>Return a Point guaranteed to lie on the surface</para>
-
- <para>Implemented using GEOS</para>
-
- <para>OGC SPEC 3.2.14.2 and 3.2.18.2 -</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Boundary(geometry)</term>
-
- <listitem>
- <para>Returns the closure of the combinatorial boundary of this
- Geometry. The combinatorial boundary is defined as described in
- section 3.12.3.2 of the OGC SPEC. Because the result of this
- function is a closure, and hence topologically closed, the
- resulting boundary can be represented using representational
- geometry primitives as discussed in the OGC SPEC, section
- 3.12.2.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>OGC SPEC s2.1.1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Buffer(geometry, double, [integer])</term>
-
- <listitem>
- <para>Returns a geometry that represents all points whose
- distance from this Geometry is less than or equal to distance.
- Calculations are in the Spatial Reference System of this
- Geometry. The optional third parameter sets the number of
- segment used to approximate a quarter circle (defaults to 8).</para>
-
- <para>Performed by the GEOS module.</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_ConvexHull(geometry)</term>
-
- <listitem>
- <para>The convex hull of a geometry represents the minimum closed geometry that encloses all geometries within the set. </para>
- <para>It is usually used with MULTI and Geometry Collections. Although it is not an aggregate - you can use it in conjunction with ST_Collect to get the convex hull of a set of points.
- ST_ConvexHull(ST_Collect(somepointfield)). It is often used to determine an affected area based on a set of point observations.
- </para>
- <programlisting>SELECT d.disease_type, ST_ConvexHull(ST_Collect(d.the_geom)) As the_geom
- FROM disease_obs As d
- GROUP BY d.disease_type</programlisting>
-
- <para>Performed by the GEOS module</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Intersection(geometry, geometry)</term>
-
- <listitem>
- <para>Returns a geometry that represents the point set
- intersection of the Geometries. </para>
- <para>In other words - that portion of geometry A and geometry B that is shared between the two geometries.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Shift_Longitude(geometry)</term>
- <listitem>
- <para>Reads every point/vertex in every component of every feature in a geometry, and if the longitude coordinate is <0, adds 360 to it. The result would be a 0-360 version of the data to be plotted in a 180 centric map</para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>ST_SymDifference(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns a geometry that represents the portions of A and B that do not intersect. It is
- called a symmetric difference because ST_SymDifference(A,B) = ST_SymDifference(B,A).</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Difference(geometry A, geometry B)</term>
-
- <listitem>
- <para>Returns a geometry that represents that part of geometry A that does not intersect
- with geometry B.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>Do not call with a GeometryCollection as an argument</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Union(geometry, geometry)</term>
-
- <listitem>
- <para>Returns a geometry that represents the point set union of
- the Geometries.</para>
-
- <para>Performed by the GEOS module.</para>
-
- <para>Do not call with a GeometryCollection as an argument.</para>
-
- <para>NOTE: this function was formerly called GeomUnion(),
- which was renamed from "Union" because
- UNION is an SQL reserved word.</para>
-
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Union(geometry set)</term>
-
- <listitem>
- <para>Returns a geometry that represents the point set union of
- all Geometries in given set.</para>
-
- <para>Performed by the GEOS module.</para>
-
- <para>Do not call with a GeometryCollection in the argument set.</para>
-
- <para>Not explicitly defined in OGC SPEC.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MemUnion(geometry set)</term>
-
- <listitem>
- <para>Same as the above, only memory-friendly (uses less memory
- and more processor time).</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Accessors</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_AsText(geometry)</term>
-
- <listitem>
- <para>Return the Well-Known Text representation of the geometry.
- For example: POLYGON(0 0,0 1,1 1,1 0,0 0)</para>
-
- <para>OGC SPEC s2.1.1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsBinary(geometry)</term>
-
- <listitem>
- <para>Returns the geometry in the OGC
- "well-known-binary" format, using the endian encoding of
- the server on which the database is running. This is useful in
- binary cursors to pull data out of the database without
- converting it to a string representation.</para>
-
- <para>OGC SPEC s2.1.1.1 - also see
- asBinary(<geometry>,'XDR') and
- asBinary(<geometry>,'NDR')</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SRID(geometry)</term>
-
- <listitem>
- <para>Returns the integer SRID number of the spatial reference
- system of the geometry.</para>
-
- <para>OGC SPEC s2.1.1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Dimension(geometry)</term>
-
- <listitem>
- <para>The inherent dimension of this Geometry object, which must
- be less than or equal to the coordinate dimension. OGC SPEC
- s2.1.1.1 - returns 0 for points, 1 for lines, 2 for polygons,
- and the largest dimension of the components of a
- GEOMETRYCOLLECTION.</para>
-
- <programlisting>SELECT ST_dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0),POINT(0 0))');
-dimension
------------
-1</programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Envelope(geometry)</term>
-
- <listitem>
- <para>Returns a vald geometry (POINT, LINESTRING or POLYGON)
- representing the bounding box of the geometry. Degenerate
- cases (vertical lines, point) will return a geometry of
- lower dimension than POLYGON.</para>
-
- <para>OGC SPEC s2.1.1.1 - The minimum bounding box for this
- Geometry, returned as a Geometry. The polygon is defined by the
- corner points of the bounding box ((MINX, MINY), (MAXX, MINY),
- (MAXX, MAXY), (MINX, MAXY), (MINX, MINY)).</para>
-
- <para>NOTE:PostGIS will add a Zmin/Zmax coordinate as well.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsEmpty(geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is the empty geometry .
- If true, then this Geometry represents the empty point set -
- i.e. GEOMETRYCOLLECTION(EMPTY).</para>
-
- <para>OGC SPEC s2.1.1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="IsSimple">
- <term>ST_IsSimple(geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry has no anomalous
- geometric points, such as self intersection or self tangency.</para>
-
- <para>Performed by the GEOS module</para>
-
- <para>OGC SPEC s2.1.1.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="IsClosed">
- <term>ST_IsClosed(geometry)</term>
-
- <listitem>
- <para>Returns true of the geometry start and end points are
- coincident.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsRing(geometry)</term>
-
- <listitem>
- <para>Returns 1 (TRUE) if this Curve is closed (StartPoint ( ) =
- EndPoint ( )) and this Curve is simple (does not pass through
- the same point more than once).</para>
-
- <para>performed by GEOS</para>
-
- <para>OGC spec 2.1.5.1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumGeometries(geometry)</term>
-
- <listitem>
- <para>If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
- number of geometries, otherwise return NULL.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeometryN(geometry,int)</term>
-
- <listitem>
- <para>Return the N'th geometry if the geometry is a
- GEOMETRYCOLLECTION, MULTIPOINT, MULTILINESTRING or MULTIPOLYGON.
- Otherwise, return NULL.</para>
-
- <note>
- <para>Index is 1-based as for OGC specs since version 0.8.0.
- Previous versions implemented this as 0-based instead.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumPoints(geometry)</term>
-
- <listitem>
- <para>Find and return the number of points in the first
- linestring in the geometry. Return NULL if there is no
- linestring in the geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointN(geometry,integer)</term>
-
- <listitem>
- <para>Return the N'th point in the first linestring in the
- geometry. Return NULL if there is no linestring in the geometry.</para>
-
- <note>
- <para>Index is 1-based as for OGC specs since version 0.8.0.
- Previous versions implemented this as 0-based instead.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_ExteriorRing(geometry)</term>
-
- <listitem>
- <para>Return the exterior ring of the polygon geometry. Return
- NULL if the geometry is not a polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumInteriorRings(geometry)</term>
-
- <listitem>
- <para>Return the number of interior rings of the first polygon
- in the geometry. Return NULL if there is no polygon in the
- geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumInteriorRing(geometry)</term>
-
- <listitem>
- <para>Synonym to NumInteriorRings(geometry). The OpenGIS specs
- are ambiguous about the exact function naming, so we provide
- both spellings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_InteriorRingN(geometry,integer)</term>
-
- <listitem>
- <para>Return the N'th interior ring of the polygon geometry.
- Return NULL if the geometry is not a polygon or the given N is
- out of range.</para>
-
- <note>
- <para>Index is 1-based as for OGC specs since version 0.8.0.
- Previous versions implemented this as 0-based instead.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_EndPoint(geometry)</term>
-
- <listitem>
- <para>Returns the last point of the LineString geometry as a
- point.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="StartPoint">
- <term>ST_StartPoint(geometry)</term>
-
- <listitem>
- <para>Returns the first point of the LineString geometry as a
- point.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="GeometryType">
- <term>GeometryType(geometry)</term>
-
- <listitem>
- <para>Returns the type of the geometry as a string. Eg:
- 'LINESTRING', 'POLYGON', 'MULTIPOINT',
- etc.</para>
-
- <para>OGC SPEC s2.1.1.1 - Returns the name of the instantiable
- subtype of Geometry of which this Geometry instance is a member.
- The name of the instantiable subtype of Geometry is returned as
- a string.</para>
-
- <note>
- <para>This function also indicates if the geometry is
- measured, by returning a string of the form 'POINTM'.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeometryType(geometry)</term>
-
- <listitem>
- <para>Returns the type of the geometry as a string. EG:
- 'Linestring', 'Polygon', etc. This function
- differs from GeometryType(geometry) in the case of the string
- that is returned, as well as the fact that it will not indicate
- whether the geometry is measured.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_X(geometry)</term>
-
- <listitem>
- <para>Return the X coordinate of the point. Input must be a
- point.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Y(geometry)</term>
-
- <listitem>
- <para>Return the Y coordinate of the point. Input must be a
- point.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Z(geometry)</term>
-
- <listitem>
- <para>Return the Z coordinate of the point, or NULL if not
- available. Input must be a point.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_M(geometry)</term>
-
- <listitem>
- <para>Return the M coordinate of the point, or NULL if not
- available. Input must be a point.</para>
-
- <note>
- <para>This is not (yet) part of the OGC spec, but is listed
- here to complete the point coordinate extractor function list.</para>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Constructors</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_GeomFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a Point</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a Line</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LinestringFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>from the conformance suite</para>
-
- <para>Throws an error if the WKT is not a Line</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolyFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a Polygon</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolygonFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>from the conformance suite</para>
-
- <para>Throws an error if the WKT is not a Polygon</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPointFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a MULTIPOINT</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MLineFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a MULTILINESTRING</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPolyFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a MULTIPOLYGON</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomCollFromText(text,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKT with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
-
- <para>Throws an error if the WKT is not a GEOMETRYCOLLECTION</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
- suite</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeometryFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a POINT</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a LINESTRING</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LinestringFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>from the conformance suite</para>
-
- <para>throws an error if WKB is not a LINESTRING</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolyFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a POLYGON</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolygonFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>from the conformance suite</para>
-
- <para>throws an error if WKB is not a POLYGON</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPointFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a MULTIPOINT</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MLineFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a MULTILINESTRING</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPolyFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a MULTIPOLYGON</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomCollFromWKB(bytea,[<srid>])</term>
-
- <listitem>
- <para>Makes a Geometry from WKB with the given SRID. If SRID is
- not give, it defaults to -1.</para>
-
- <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
- suite</para>
-
- <para>throws an error if WKB is not a GEOMETRYCOLLECTION</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="BdPolyFromText">
- <term>ST_BdPolyFromText(text WKT, integer SRID)</term>
-
- <listitem>
- <para>Construct a Polygon given an arbitrary collection of
- closed linestrings as a MultiLineString text representation.</para>
-
- <para>Throws an error if WKT is not a MULTILINESTRING. Throws an
- error if output is a MULTIPOLYGON; use <link
- linkend="BdMPolyFromText">BdMPolyFromText</link> in that case,
- or see <link linkend="BuildArea">BuildArea()</link> for a
- postgis-specific approach.</para>
-
- <para>OGC SFSQL 1.1 - 3.2.6.2</para>
-
- <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="BdMPolyFromText">
- <term>ST_BdMPolyFromText(text WKT, integer SRID)</term>
-
- <listitem>
- <para>Construct a MultiPolygon given an arbitrary collection of
- closed linestrings as a MultiLineString text representation.</para>
-
- <para>Throws an error if WKT is not a MULTILINESTRING. Forces
- MULTIPOLYGON output even when result is really only composed by
- a single POLYGON; use <link linkend="BdPolyFromText">BdPolyFromText</link>
- if you're sure a single POLYGON will result from operation,
- or see <link linkend="BuildArea">BuildArea()</link> for a
- postgis-specific approach.</para>
-
- <para>OGC SFSQL 1.1 - 3.2.6.2</para>
-
- <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
- </sect1>
-
- <sect1>
- <title>PostGIS Extensions</title>
-
- <sect2>
- <title>Management Functions</title>
-
- <variablelist>
- <varlistentry>
- <term>DropGeometryTable([<schema_name>],
- <table_name>)</term>
-
- <listitem>
- <para>Drops a table and all its references in geometry_columns.
- Note: uses current_schema() on schema-aware pgsql installations
- if schema is not provided.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>UpdateGeometrySRID([<schema_name>],
- <table_name>, <column_name>, <srid>)</term>
-
- <listitem>
- <para>Update the SRID of all features in a geometry column
- updating constraints and reference in geometry_columns. Note:
- uses current_schema() on schema-aware pgsql installations if
- schema is not provided.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>update_geometry_stats([<table_name>,
- <column_name>])</term>
-
- <listitem>
- <para>Update statistics about spatial tables for use by the
- query planner. You will also need to run "VACUUM ANALYZE
- [table_name] [column_name]" for the statistics gathering
- process to be complete. NOTE: starting with PostgreSQL 8.0
- statistics gathering is automatically performed running
- "VACUUM ANALYZE".</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_version()</term>
-
- <listitem>
- <para>Returns PostGIS version number and compile-time options</para>
-
- <note>
- <para>Prior to version 1.1.0 this was a procedural function,
- thus possibly returning inaccurate information (in case of
- incomplete database upgrades).</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry id="postgis_lib_version">
- <term>postgis_lib_version()</term>
-
- <listitem>
- <para>Returns the version number of the PostGIS library.</para>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_lib_build_date()</term>
-
- <listitem>
- <para>Returns build date of the PostGIS library.</para>
-
- <para>Availability: 1.0.0RC1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_script_build_date()</term>
-
- <listitem>
- <para>Returns build date of the PostGIS scripts.</para>
-
- <para>Availability: 1.0.0RC1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_scripts_installed()</term>
-
- <listitem>
- <para>Returns version of the postgis scripts installed in this
- database.</para>
-
- <note>
- <para>If the output of this function doesn't match the
- output of <link linkend="postgis_scripts_released">postgis_scripts_released()</link>
- you probably missed to properly upgrade an existing database.
- See the <link linkend="upgrading">Upgrading</link> section for
- more info.</para>
- </note>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="postgis_scripts_released">
- <term>postgis_scripts_released()</term>
-
- <listitem>
- <para>Returns the version number of the lwpostgis.sql script
- released with the installed postgis lib.</para>
-
- <note>
- <para>Starting with version 1.1.0 this function returns the
- same value of <link linkend="postgis_lib_version">postgis_lib_version()</link>.
- Kept for backward compatibility.</para>
- </note>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_geos_version()</term>
-
- <listitem>
- <para>Returns the version number of the GEOS library, or NULL if
- GEOS support is not enabled.</para>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_jts_version()</term>
-
- <listitem>
- <para>Returns the version number of the JTS library, or NULL if
- JTS support is not enabled.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_proj_version()</term>
-
- <listitem>
- <para>Returns the version number of the PROJ4 library, or NULL
- if PROJ4 support is not enabled.</para>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>postgis_uses_stats()</term>
-
- <listitem>
- <para>Returns true if STATS usage has been enabled, false
- otherwise.</para>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="postgis_full_version">
- <term>postgis_full_version()</term>
-
- <listitem>
- <para>Reports full postgis version and build configuration
- infos.</para>
-
- <para>Availability: 0.9.0</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Operators</title>
-
- <variablelist>
- <varlistentry>
- <term>A &< B</term>
-
- <listitem>
- <para>The "&<" operator returns true if A's
- bounding box overlaps or is to the left of B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A &> B</term>
-
- <listitem>
- <para>The "&>" operator returns true if A's
- bounding box overlaps or is to the right of B's bounding
- box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A << B</term>
-
- <listitem>
- <para>The "<<" operator returns true if A's
- bounding box is strictly to the left of B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A >> B</term>
-
- <listitem>
- <para>The ">>" operator returns true if A's
- bounding box is strictly to the right of B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A &<| B</term>
-
- <listitem>
- <para>The "&<|" operator returns true if A's
- bounding box overlaps or is below B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A |&> B</term>
-
- <listitem>
- <para>The "|&>" operator returns true if A's
- bounding box overlaps or is above B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A <<| B</term>
-
- <listitem>
- <para>The "<<|" operator returns true if A's
- bounding box is strictly below B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A |>> B</term>
-
- <listitem>
- <para>The "|>>" operator returns true if A's
- bounding box is strictly above B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A ~= B</term>
-
- <listitem>
- <para>The "~=" operator is the "same as"
- operator. It tests actual geometric equality of two features. So
- if A and B are the same feature, vertex-by-vertex, the operator
- returns true.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A @ B</term>
-
- <listitem>
- <para>The "@" operator returns true if A's bounding
- box is completely contained by B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A ~ B</term>
-
- <listitem>
- <para>The "~" operator returns true if A's bounding
- box completely contains B's bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>A && B</term>
-
- <listitem>
- <para>The "&&" operator is the
- "overlaps" operator. If A's bounding box overlaps
- B's bounding box the operator returns true.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Measurement Functions</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_area2d(geometry)</term>
-
- <listitem>
- <para>Returns the area of the geometry if it is a polygon or
- multi-polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_distance_sphere(point, point)</term>
-
- <listitem>
- <para>Returns linear distance in meters between two lat/lon
- points. Uses a spherical earth and radius of 6370986 meters.
- Faster than <link linkend="distance_spheroid">distance_spheroid()</link>,
- but less accurate. Only implemented for points.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="distance_spheroid">
- <term>ST_distance_spheroid(point, point, spheroid)</term>
-
- <listitem>
- <para>Returns linear distance between two lat/lon points given a
- particular spheroid. See the explanation of spheroids given for
- <link linkend="length_spheroid">length_spheroid()</link>.
- Currently only implemented for points.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="length2d">
- <term>ST_length2d(geometry)</term>
-
- <listitem>
- <para>Returns the 2-dimensional length of the geometry if it is
- a linestring or multi-linestring.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_length3d(geometry)</term>
-
- <listitem>
- <para>Returns the 3-dimensional length of the geometry if it is
- a linestring or multi-linestring.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="length_spheroid">
- <term>ST_length_spheroid(geometry,spheroid)</term>
-
- <listitem>
- <para>Calculates the length of of a geometry on an ellipsoid.
- This is useful if the coordinates of the geometry are in
- latitude/longitude and a length is desired without reprojection.
- The ellipsoid is a separate database type and can be constructed
- as follows:</para>
-
- <literallayout>SPHEROID[<NAME>,<SEMI-MAJOR
- AXIS>,<INVERSE FLATTENING>]</literallayout>
-
- <para>Eg:</para>
-
- <literallayout>SPHEROID["GRS_1980",6378137,298.257222101]</literallayout>
-
- <para>An example calculation might look like this:</para>
-
- <literallayout>SELECT length_spheroid( geometry_column,
- 'SPHEROID["GRS_1980",6378137,298.257222101]' )
- FROM geometry_table;</literallayout>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_length3d_spheroid(geometry,spheroid)</term>
-
- <listitem>
- <para>Calculates the length of of a geometry on an ellipsoid,
- taking the elevation into account. This is just like
- length_spheroid except vertical coordinates (expressed in the
- same units as the spheroid axes) are used to calculate the extra
- distance vertical displacement adds.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_distance(geometry, geometry)</term>
-
- <listitem>
- <para>Returns the smaller distance between two geometries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_max_distance(linestring,linestring)</term>
-
- <listitem>
- <para>Returns the largest distance between two line strings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_perimeter(geometry)</term>
-
- <listitem>
- <para>Returns the 2-dimensional perimeter of the geometry, if it
- is a polygon or multi-polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_perimeter2d(geometry)</term>
-
- <listitem>
- <para>Returns the 2-dimensional perimeter of the geometry, if it
- is a polygon or multi-polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_perimeter3d(geometry)</term>
-
- <listitem>
- <para>Returns the 3-dimensional perimeter of the geometry, if it
- is a polygon or multi-polygon.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_azimuth(geometry, geometry)</term>
-
- <listitem>
- <para>Returns the azimuth of the segment defined by the given
- Point geometries, or NULL if the two points are coincident.
- Return value is in radians.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Outputs</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_AsBinary(geometry,{'NDR'|'XDR'})</term>
-
- <listitem>
- <para>Returns the geometry in the OGC
- "well-known-binary" format as a bytea, using
- little-endian (NDR) or big-endian (XDR) encoding. This is useful
- in binary cursors to pull data out of the database without
- converting it to a string representation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsEWKT(geometry)</term>
-
- <listitem>
- <para>Returns a Geometry in EWKT format (as text).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsEWKB(geometry, {'NDR'|'XDR'})</term>
-
- <listitem>
- <para>Returns a Geometry in EWKB format (as bytea) using either
- little-endian (NDR) or big-endian (XDR) encoding.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsHEXEWKB(geometry, {'NDR'|'XDR'})</term>
-
- <listitem>
- <para>Returns a Geometry in HEXEWKB format (as text) using
- either little-endian (NDR) or big-endian (XDR) encoding.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsSVG(geometry, [rel], [precision])</term>
-
- <listitem>
- <para>Return the geometry as SVG path data. Use 1 as second argument to have the
- path data implemented in terms of relative moves, the default (or 0) uses
- absolute moves. Third argument may be used to reduce the maximum number of
- decimal digits used in output (defaults to 15). Point geometries will be
- rendered as cx/cy when 'rel' arg is 0, x/y when 'rel' is 1. Multipoint
- geometries are delimited by commas (","), GeometryCollection geometries are
- delimited by semicolons (";").</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsGML([version], geometry, [precision])</term>
-
- <listitem>
- <para>Return the geometry as a GML element. The version parameter,
- if specified, may be either 2 or 3. If no version parameter is
- specified then the default is assumed to be 2. The third argument may
- be used to reduce the maximum number of significant digits used
- in output (defaults to 15).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsKML(geometry, [precision])</term>
-
- <listitem>
- <para>Return the geometry as a KML element. Second argument may
- be used to reduce the maximum number of significant digits used
- in output (defaults to 15).</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ST_AsGeoJson([version], geometry, [precision], [options])</term>
-
- <listitem>
- <para>
- Return the geometry as a GeoJson element. (Cf <ulink
- url="http://wiki.geojson.org/GeoJSON_draft_version_6">GeoJson
- specifications 1.0 RC6</ulink>).
- 2D and 3D Geometries are both supported. GeoJson only support
- SFS 1.1 geometry type (no curve support for example).
- </para>
- <para>
- The version parameter, if specified, must be 1.
- </para>
- <para>
- The third argument may be used to reduce the maximum number of
- significant digits used in output (defaults to 15).
- </para>
- <para>
- The last 'options' argument could be used to add Bbox
- or Crs in GeoJSON output:
- <itemizedlist>
- <listitem>
- <para>0: means no option (default value)</para>
- </listitem>
- <listitem>
- <para>1: GeoJson CRS</para>
- </listitem>
- <listitem>
- <para>2: GeoJson Bbox</para>
- </listitem>
- <listitem>
- <para>2: Both GeoJson Bbox and CRS</para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Constructors</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_GeomFromEWKT(text)</term>
-
- <listitem>
- <para>Makes a Geometry from EWKT.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomFromEWKB(bytea)</term>
-
- <listitem>
- <para>Makes a Geometry from EWKB.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakePoint(<x>, <y>, [<z>],
- [<m>])</term>
-
- <listitem>
- <para>Creates a 2d,3dz or 4d point geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakePointM(<x>, <y>, <m>)</term>
-
- <listitem>
- <para>Creates a 3dm point geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakeBox2D(<LL>, <UR>)</term>
-
- <listitem>
- <para>Creates a BOX2D defined by the given point geometries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakeBox3D(<LLB>, <URT>)</term>
-
- <listitem>
- <para>Creates a BOX3D defined by the given point geometries.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakeLine(geometry set)</term>
-
- <listitem>
- <para>Creates a Linestring from a set of point geometries. You
- might want to use a subselect to order points before feeding
- them to this aggregate.</para>
- <programlisting>
-SELECT gps.gps_track, ST_MakeLine(gps.the_geom) As newgeom
- FROM (SELECT gps_track,gps_time, the_geom
- FROM gps_points ORDER BY gps_track, gps_time) As gps
- GROUP BY gps.gps_track
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakeLine(geometry, geometry)</term>
-
- <listitem>
- <para>Creates a Linestring from the two given point geometries.</para>
- <programlisting>
-SELECT ST_AsText(ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)))
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineFromMultiPoint(multipoint)</term>
-
- <listitem>
- <para>Creates a LineString from a MultiPoint geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MakePolygon(linestring geometry)</term>
-
- <listitem>
- <para>Creates a Polygon formed by the given shell. Input geometries must be closed
- LINESTRINGS (see <link linkend="IsClosed">ST_IsClosed</link> and
- <link linkend="GeometryType">ST_GeometryType</link>). This function will not accept a MULTILINESTRING.</para>
- <programlisting>
-SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'));
---If linestring is not closed
---you can add the start point to close it
-SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)))
-FROM (
-SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo
- </programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ST_MakePolygon(linestring geometry, linestrings geometry[])</term>
- <listitem>
- <para>Creates a Polygon formed by the given shell and array of
- holes. You can construct a geometry array using <link
- linkend="Accum">ST_Accum</link> or the PostgreSQL ARRAY[] and ARRAY() constructs. Input geometries must be closed
- LINESTRINGS (see <link linkend="IsClosed">ST_IsClosed</link> and
- <link linkend="GeometryType">ST_GeometryType</link>).</para>
- <programlisting>
---Build a donut with an ant hole
-SELECT ST_MakePolygon(
- ST_ExteriorRing(ST_Buffer(foo.line,10)),
- ARRAY[ST_Translate(foo.line,1,1),
- ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
- )
-FROM
- (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10))
- As line )
- As foo
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry id="BuildArea">
- <term>ST_BuildArea(geometry)</term>
-
- <listitem>
- <para>Creates an areal geometry formed by the constituent
- linework of given geometry. The return type can be a Polygon or
- MultiPolygon, depending on input. If the input lineworks do not
- form polygons NULL is returned.</para>
-
- <para>See also <link linkend="BdPolyFromText">BdPolyFromText</link>
- and <link linkend="BdMPolyFromText">BdMPolyFromText</link> -
- wrappers to this function with standard OGC interface.</para>
-
- <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Polygonize(geometry set)</term>
-
- <listitem>
- <para>Aggregate. Creates a GeometryCollection containing
- possible polygons formed from the constituent linework of a set
- of geometries.</para>
-
- <para>Availability: 1.0.0RC1 - requires GEOS >= 2.1.0.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Collect(geometry set)</term>
-
- <listitem>
- <para>This function returns a GEOMETRYCOLLECTION or a MULTI
- object from a set of geometries. The collect() function is an
- "aggregate" function in the terminology of PostgreSQL.
- That means that it operates on rows of data, in the same way
- the SUM() and AVG() functions do. For example, "SELECT
- ST_Collect(GEOM) FROM GEOMTABLE GROUP BY ATTRCOLUMN" will
- return a separate GEOMETRYCOLLECTION for each distinct value of
- ATTRCOLUMN.</para>
- <para>ST_Collect and ST_Union are often interchangeable.
- ST_Collect is in general orders of magnitude faster than ST_Union because it does not try to dissolve
- boundaries. It merely rolls up single geometries into MULTI and MULTI or mixed geometry types into Geometry Collections.
- Unfortunately geometry collections are not well-supported by
- GIS tools. To prevent ST_Collect from returning a Geometry Collection when collecting MULTI geometries,
- one can use the below trick that utilizes ST_Dump to expand the MULTIs out to singles and then regroup them.
- </para>
- <programlisting>
-Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
-SELECT stusps,
- ST_Multi(ST_Collect(f.the_geom)) as singlegeom
- FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom
- FROM
- somestatetable ) As f
-GROUP BY stusps
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Collect(geometry, geometry)</term>
-
- <listitem>
- <para>This function returns a geometry being a collection of two
- input geometries. Output type can be a MULTI* or a
- GEOMETRYCOLLECTION.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Dump(geometry)</term>
-
- <listitem>
- <para>This is a set-returning function (SRF). It returns a set
- of geometry_dump rows, formed by a geometry (geom) and an array
- of integers (path). When the input geometry is a simple type
- (POINT,LINESTRING,POLYGON) a single record will be returned with
- an empty path array and the input geometry as geom. When the
- input geometry is a collection or multi it will return a record
- for each of the collection components, and the path will express
- the position of the component inside the collection.</para>
-
- <para>ST_Dump is useful for expanding geometries. It is the reverse of a GROUP BY in that
- it creates new rows. For example it can be use to expand MULTIPOLYGONS into POLYGONS.</para>
-
- <programlisting>
-SELECT sometable.field1, sometable.field1,
-(ST_Dump(sometable.the_geom)).geom As the_geom
- FROM sometable
- </programlisting>
-
-
- <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
- higher.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_DumpRings(geometry)</term>
-
- <listitem>
- <para>This is a set-returning function (SRF). It returns a set
- of geometry_dump rows, formed by a geometry (geom) and an array
- of integers (path). The 'path' field holds the polygon
- ring index, contains a single element: 0 for the shell, hole
- number for holes. The 'geom' field contains the
- corresponding ring as a polygon.</para>
-
- <para>Availability: PostGIS 1.1.3. Requires PostgreSQL 7.3 or
- higher.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Geometry Editors</title>
-
- <variablelist>
- <varlistentry id="addbbox">
- <term>ST_AddBBOX(geometry)</term>
-
- <listitem>
- <para>Add bounding box to the geometry. This would make bounding
- box based queries faster, but will increase the size of the
- geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="dropbbox">
- <term>ST_DropBBOX(geometry)</term>
-
- <listitem>
- <para>Drop the bounding box cache from the geometry. This
- reduces geometry size, but makes bounding-box based queries
- slower.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AddPoint(linestring geometry, point geometry)</term>
- <term>ST_AddPoint(linestring geometry, point geometry, position integer)</term>
-
- <listitem>
- <para>Adds a point to a LineString before point <position>
- (0-based index). Third parameter can be omitted or set to -1 for
- appending.</para>
- <programlisting>
---guarantee all linestrings in a table are closed
---by adding the start point of each linestring to the end of the line string
---only for those that are not closed
-UPDATE sometable
- SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
- FROM sometable
- WHERE ST_IsClosed(the_geom) = false;
- </programlisting>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_RemovePoint(linestring, offset)</term>
-
- <listitem>
- <para>Removes point from a linestring. Offset is 0-based.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SetPoint(linestring, N, point)</term>
-
- <listitem>
- <para>Replace point N of linestring with given point. Index is
- 0-based.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Force_collection(geometry)</term>
-
- <listitem>
- <para>Converts the geometry into a GEOMETRYCOLLECTION. This is
- useful for simplifying the WKB representation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="force_2d">
- <term>ST_Force_2d(geometry)</term>
-
- <listitem>
- <para>Forces the geometries into a "2-dimensional mode"
- so that all output representations will only have the X and Y
- coordinates. This is useful for force OGC-compliant output
- (since OGC only specifies 2-D geometries).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="force_3dz">
- <term>ST_Force_3dz(geometry)</term>
-
- <term>ST_Force_3d(geometry)</term>
-
- <listitem>
- <para>Forces the geometries into XYZ mode.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="force_3dm">
- <term>ST_Force_3dm(geometry)</term>
-
- <listitem>
- <para>Forces the geometries into XYM mode.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="force_4d">
- <term>ST_Force_4d(geometry)</term>
-
- <listitem>
- <para>Forces the geometries into XYZM mode.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Multi(geometry)</term>
-
- <listitem>
- <para>Returns the geometry as a MULTI* geometry. If the geometry
- is already a MULTI*, it is returned unchanged.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Transform(geometry,integer)</term>
-
- <listitem>
- <para>Returns a new geometry with its coordinates transformed to
- the SRID referenced by the integer parameter. The destination
- SRID must exist in the <varname>SPATIAL_REF_SYS</varname> table.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Affine(geometry, float8, float8, float8, float8, float8,
- float8, float8, float8, float8, float8, float8, float8)</term>
-
- <listitem>
- <para>Applies an 3d affine transformation to the geometry. The
- call <programlisting>Affine(geom, a, b, c, d, e, f, g, h, i, xoff, yoff, zoff) </programlisting> represents the transformation matrix
- <programlisting>/ a b c xoff \
-| d e f yoff |
-| g h i zoff |
-\ 0 0 0 1 /</programlisting> and the
- vertices are transformed as follows:
- <programlisting>x' = a*x + b*y + c*z + xoff
-y' = d*x + e*y + f*z + yoff
-z' = g*x + h*y + i*z + zoff</programlisting> All of the translate / scale functions below
- are expressed via such an affine transformation.</para>
-
- <para>Availability: 1.1.2.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Affine(geometry, float8, float8, float8, float8, float8,
- float8)</term>
-
- <listitem>
- <para>Applies an 2d affine transformation to the geometry. The
- call <programlisting>Affine(geom, a, b, d, e, xoff, yoff)</programlisting> represents the transformation matrix
- <programlisting>/ a b 0 xoff \ / a b xoff \
-| d e 0 yoff | rsp. | d e yoff |
-| 0 0 1 0 | \ 0 0 1 /
-\ 0 0 0 1 /</programlisting>
- and the vertices are transformed as follows:
- <programlisting>x' = a*x + b*y + xoff
-y' = d*x + e*y + yoff
-z' = z </programlisting> This method is a subcase of
- the 3D method above.</para>
-
- <para>Availability: 1.1.2.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Translate(geometry, float8, float8, float8)</term>
-
- <listitem>
- <para>Translates the geometry to a new location using the
- numeric parameters as offsets. Ie: translate(geom, X, Y, Z).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Scale(geometry, float8, float8, float8)</term>
-
- <listitem>
- <para>scales the geometry to a new size by multiplying the
- ordinates with the parameters. Ie: scale(geom, Xfactor, Yfactor,
- Zfactor).</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="Rotate">
- <term>ST_RotateZ(geometry, float8)</term>
-
- <term>ST_RotateX(geometry, float8)</term>
-
- <term>ST_RotateY(geometry, float8)</term>
-
- <listitem>
- <para>Rotate the geometry around the Z, X or Y axis by the given
- angle given in radians. Follows the right-hand rule.</para>
-
- <para>Availability: 1.1.2.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_TransScale(geometry, float8, float8, float8, float8)</term>
-
- <listitem>
- <para>First, translates the geometry using the first two floats,
- then scales it using the second two floats, working in 2D only.
- Using <code>transscale(geom, X, Y, XFactor, YFactor)</code>
- internally calls <code>affine(geom, XFactor, 0, 0, 0, YFactor,
- 0, 0, 0, 1, X*XFactor, Y*YFactor, 0)</code>.</para>
-
- <para>Availability: 1.1.0.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Reverse(geometry)</term>
-
- <listitem>
- <para>Returns the geometry with vertex order reversed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_ForceRHR(geometry)</term>
-
- <listitem>
- <para>Force polygons of the collection to obey Right-Hand-Rule.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Simplify(geometry, tolerance)</term>
-
- <listitem>
- <para>Returns a "simplified" version of the given
- geometry using the Douglas-Peuker algorithm. Will actually do
- something only with (multi)lines and (multi)polygons but you can
- safely call it with any kind of geometry. Since simplification
- occurs on a object-by-object basis you can also feed a
- GeometryCollection to this function. Note that returned geometry
- might loose its simplicity (see <link linkend="IsSimple">IsSimple</link>)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SimplifyPreserveTopology(geometry, tolerance)</term>
- <listitem>
- <para>Returns a "simplified" version of the given
- geometry using the Douglas-Peuker algorithm. Will avoid
- creating derived geometries (polygons in particular) that
- are invalid.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SnapToGrid(geometry, originX, originY, sizeX, sizeY)</term>
-
- <term>ST_SnapToGrid(geometry, sizeX, sizeY)</term>
-
- <term>ST_SnapToGrid(geometry, size)</term>
-
- <listitem>
- <para>Snap all points of the input geometry to the grid defined
- by its origin and cell size. Remove consecutive points falling
- on the same cell, eventually returning NULL if output points are
- not enough to define a geometry of the given type. Collapsed
- geometries in a collection are stripped from it.</para>
-
- <note>
- <para>The returned geometry might loose its simplicity (see
- <link linkend="IsSimple">IsSimple</link>).</para>
- </note>
-
- <note>
- <para>Before release 1.1.0 this function always returned a 2d
- geometry. Starting at 1.1.0 the returned geometry will have
- same dimensionality as the input one with higher dimension
- values untouched. Use the version taking a second geometry
- argument to define all grid dimensions.</para>
- </note>
-
- <para>Availability: 1.0.0RC1</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SnapToGrid(geometry, geometry, sizeX, sizeY, sizeZ,
- sizeM)</term>
-
- <listitem>
- <para>Snap all points of the input geometry to the grid defined
- by its origin (the second argument, must be a point) and cell
- sizes. Specify 0 as size for any dimension you don't want to
- snap to a grid.</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Segmentize(geometry, maxlength)</term>
-
- <listitem>
- <para>Return a modified geometry having no segment longer then
- the given distance. Interpolated points will have Z and M values
- (if needed) set to 0. Distance computation is performed in 2d
- only.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineMerge(geometry)</term>
-
- <listitem>
- <para>Returns a (set of) LineString(s) formed by sewing together
- constituent linework of input.</para>
-
- <para>Availability: 1.1.0 - requires GEOS >= 2.1.0</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Linear Referencing</title>
-
- <variablelist>
- <varlistentry id="line_interpolate_point">
- <term>ST_line_interpolate_point(linestring, location)</term>
-
- <listitem>
- <para>Returns a point interpolated along a line. First argument
- must be a LINESTRING. Second argument is a float8 between 0 and
- 1 representing fraction of total <link linkend="length2d">2d
- length</link> the point has to be located.</para>
-
- <para>See <link linkend="line_locate_point">line_locate_point()</link>
- for computing the line location nearest to a Point.</para>
-
- <note>
- <para>Since release 1.1.1 this function also interpolates M
- and Z values (when present), while prior releases set them to
- 0.0.</para>
- </note>
-
- <para>Availability: 0.8.2</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="line_substring">
- <term>ST_line_substring(linestring, start, end)</term>
-
- <listitem>
- <para>Return a linestring being a substring of the input one
- starting and ending at the given fractions of total 2d length.
- Second and third arguments are float8 values between 0 and 1.</para>
-
- <para>If 'start' and 'end' have the same value
- this is equivalent to <link linkend="line_interpolate_point">line_interpolate_point()</link>.</para>
-
- <para>See <link linkend="line_locate_point">line_locate_point()</link>
- for computing the line location nearest to a Point.</para>
-
- <note>
- <para>Since release 1.1.1 this function also interpolates M
- and Z values (when present), while prior releases set them to
- unspecified values.</para>
- </note>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="line_locate_point">
- <term>ST_line_locate_point(LineString, Point)</term>
-
- <listitem>
- <para>Returns a float between 0 and 1 representing the location
- of the closest point on LineString to the given Point, as a
- fraction of total <link linkend="length2d">2d line</link>
- length.</para>
-
- <para>You can use the returned location to extract a Point (<link
- linkend="line_interpolate_point">line_interpolate_point</link>)
- or a substring (<link linkend="line_substring">line_substring</link>).</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_locate_along_measure(geometry, float8)</term>
-
- <listitem>
- <para>Return a derived geometry collection value with elements
- that match the specified measure. Polygonal elements are not
- supported.</para>
-
- <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) -
- Text for Continuation CD Editing Meeting</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_locate_between_measures(geometry, float8, float8)</term>
-
- <listitem>
- <para>Return a derived geometry collection value with elements
- that match the specified range of measures inclusively.
- Polygonal elements are not supported.</para>
-
- <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) -
- Text for Continuation CD Editing Meeting</para>
-
- <para>Availability: 1.1.0</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2>
- <title>Misc</title>
-
- <variablelist>
- <varlistentry>
- <term>ST_Summary(geometry)</term>
-
- <listitem>
- <para>Returns a text summary of the contents of the geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_box2d(geometry)</term>
-
- <listitem>
- <para>Returns a BOX2D representing the maximum extents of the
- geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_box3d(geometry)</term>
-
- <listitem>
- <para>Returns a BOX3D representing the maximum extents of the
- geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_extent(geometry set)</term>
-
- <listitem>
- <para>The extent() function is an "aggregate" function
- in the terminology of PostgreSQL. That means that it operators
- on lists of data, in the same way the sum() and mean() functions
- do. For example, "SELECT ST_Extent(GEOM) FROM GEOMTABLE"
- will return a BOX3D giving the maximum extent of all features in
- the table. Similarly, "SELECT ST_Extent(GEOM) FROM GEOMTABLE
- GROUP BY CATEGORY" will return one extent result for each
- category.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="zmflag">
- <term>ST_zmflag(geometry)</term>
-
- <listitem>
- <para>Returns ZM (dimension semantic) flag of the geometries as
- a small int. Values are: 0=2d, 1=3dm, 2=3dz, 3=4d.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="hasbbox">
- <term>ST_HasBBOX(geometry)</term>
-
- <listitem>
- <para>Returns TRUE if the bbox of this geometry is cached, FALSE
- otherwise. Use <link linkend="addbbox">addBBOX()</link> and
- <link linkend="dropbbox">dropBBOX()</link> to control caching.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ndims">
- <term>ST_ndims(geometry)</term>
-
- <listitem>
- <para>Returns number of dimensions of the geometry as a small
- int. Values are: 2,3 or 4.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_nrings(geometry)</term>
-
- <listitem>
- <para>If the geometry is a polygon or multi-polygon returns the
- number of rings.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_npoints(geometry)</term>
-
- <listitem>
- <para>Returns the number of points in the geometry.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="IsValid">
- <term>ST_isvalid(geometry)</term>
-
- <listitem>
- <para>returns true if this geometry is valid.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_expand(geometry, float)</term>
-
- <listitem>
- <para>This function returns a bounding box expanded in all
- directions from the bounding box of the input geometry, by an
- amount specified in the second argument. Very useful for
- distance() queries, to add an index filter to the query.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_estimated_extent([schema], table, geocolumn)</term>
-
- <listitem>
- <para>Return the 'estimated' extent of the given spatial
- table. The estimated is taken from the geometry column's
- statistics. The current schema will be used if not specified.</para>
-
- <para>For PostgreSQL>=8.0.0 statistics are gathered by
- VACUUM ANALYZE and resulting extent will be about 95% of the
- real one.</para>
-
- <para>For PostgreSQL<8.0.0 statistics are gathered by
- update_geometry_stats() and resulting extent will be exact.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_find_srid(varchar,varchar,varchar)</term>
-
- <listitem>
- <para>The syntax is find_srid(<db/schema>,
- <table>, <column>) and the function returns the
- integer SRID of the specified column by searching through the
- GEOMETRY_COLUMNS table. If the geometry column has not been
- properly added with the AddGeometryColumns() function, this
- function will not work either.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_mem_size(geometry)</term>
-
- <listitem>
- <para>Returns the amount of space (in bytes) the geometry takes.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_point_inside_circle(geometry, float, float, float)</term>
-
- <listitem>
- <para>The syntax for this functions is
- point_inside_circle(<geometry>,<circle_center_x>,<circle_center_y>,<radius>).
- Returns the true if the geometry is a point and is inside the
- circle. Returns false otherwise.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_XMin(box3d) ST_YMin(box3d) ST_ZMin(box3d)</term>
-
- <listitem>
- <para>Returns the requested minima of a bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_XMax(box3d) ST_YMax(box3d) ST_ZMax(box3d)</term>
-
- <listitem>
- <para>Returns the requested maxima of a bounding box.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="Accum">
- <term>ST_Accum(geometry set)</term>
-
- <listitem>
- <para>Aggregate. Constructs an array of geometries.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- &long_xact;
- </sect1>
-
- <sect1>
- <title>SQL-MM Functions</title>
-
- <para>This is a listing of the SQL-MM defined functions that PostGIS
- currently supports. The implementations of these functions follow the
- ArcSDE implementation, and thus deviate somewhat from the spec. These
- deviations will be noted.</para>
-
- <para>As of version 1.2.0, these functions have been implemented by
- wrapping existing PostGIS functions. As a result, full support for
- curved geometries may not be in place for many functions.</para>
-
- <note>
- <para>SQL-MM defines the default SRID of all geometry constructors as
- 0. PostGIS uses a default SRID of -1.</para>
- </note>
-
- <variablelist>
- <varlistentry>
- <term>ST_Area</term>
-
- <listitem>
- <para>Return the area measurement of an ST_Surface or
- ST_MultiSurface value.</para>
-
- <para>SQL-MM 3: 8.1.2, 9.5.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsBinary</term>
-
- <listitem>
- <para>Return the well-known binary representation of an
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.37</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_AsText</term>
-
- <listitem>
- <para>Return the well-known text representation of an ST_Geometry
- value.</para>
-
- <para>SQL-MM 3: 5.1.25</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Boundary</term>
-
- <listitem>
- <para>Return the boundary of the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.14</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Buffer</term>
-
- <listitem>
- <para>Return a buffer around the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.17</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Centroid</term>
-
- <listitem>
- <para>Return mathematical centroid of the ST_Surface or
- ST_MultiSurface value.</para>
-
- <para>SQL-MM 3: 8.1.4, 9.5.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Contains</term>
-
- <listitem>
- <para>Test if an ST_Geometry value spatially contains another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.31</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_ConvexHull</term>
-
- <listitem>
- <para>The convex hull of a geometry represents the minimum geometry that encloses all geometries within the set. </para>
- <para>It is usually used with MULTI and Geometry Collections. Although it is not an aggregate - you can use it in conjunction with ST_Collect to get the convex hull of a set of points. ST_ConvexHull(ST_Collect(somepointfield)). It is often used to determine an affected area based on a set of point observations.
- </para>
-
- <para>SQL-MM 3: 5.1.16</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_CoordDim</term>
-
- <listitem>
- <para>Return the coordinate dimension of the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Crosses</term>
-
- <listitem>
- <para>Test if an ST_Geometry value spatially crosses another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.29</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Difference</term>
-
- <listitem>
- <para>Return an ST_Geometry value that represents the point set
- difference of two ST_Geometry values.</para>
-
- <para>SQL-MM 3: 5.1.20</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Dimension</term>
-
- <listitem>
- <para>Return the dimension of the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.2</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Disjoint</term>
-
- <listitem>
- <para>Test if an ST_Geometry value is spatially disjoint from
- another ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.26</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Distance</term>
-
- <listitem>
- <para>Return the distance between two geometries.</para>
-
- <para>SQL-MM 3: 5.1.23</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_EndPoint</term>
-
- <listitem>
- <para>Return an ST_Point value that is the end point of an
- ST_Curve value.</para>
-
- <para>SQL-MM 3: 7.1.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Envelope</term>
-
- <listitem>
- <para>Return the bounding rectangle for the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.15</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Equals</term>
-
- <listitem>
- <para>Test if an ST_Geometry value as spatially equal to another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.24</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_ExteriorRing</term>
-
- <listitem>
- <para>Return the exterior ring of an ST_Surface</para>
-
- <para>SQL-MM 3: 8.2.3, 8.3.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeometryN</term>
-
- <listitem>
- <para>Return the indicated ST_Geometry value from an
- ST_GeomCollection.</para>
-
- <para>SQL-MM 3: 9.1.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeometryType</term>
-
- <listitem>
- <para>Return the geometry type of the ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomFromText</term>
-
- <listitem>
- <para>Return a specified ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.40</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_GeomFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.41</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_InteriorRingN</term>
-
- <listitem>
- <para>Return the specified interior ring of an ST_Surface value.</para>
-
- <para>SQL-MM 3: 8.2.6, 8.3.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Intersection</term>
-
- <listitem>
- <para>Return an ST_Geometry value that represents the point set
- intersection of two ST_Geometry values.</para>
- <para>In other words - that portion of geometry A and geometry B that is shared between the two geometries.</para>
-
- <para>SQL-MM 3: 5.1.18</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Intersects</term>
-
- <listitem>
- <para>Test if an ST_Geometry value spatially intersects another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.27</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsClosed</term>
-
- <listitem>
- <para>Test if an ST_Curve or ST_MultiCurve value is closed.</para>
-
- <note>
- <para>SQL-MM defines the result of ST_IsClosed(NULL) to be 0,
- while PostGIS returns NULL.</para>
- </note>
-
- <para>SQL-MM 3: 7.1.5, 9.3.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsEmpty</term>
-
- <listitem>
- <para>Test if an ST_Geometry value corresponds to the empty set.</para>
-
- <note>
- <para>SQL-MM defines the result of ST_IsEmpty(NULL) to be 0,
- while PostGIS returns NULL.</para>
- </note>
-
- <para>SQL-MM 3: 5.1.7</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsRing</term>
-
- <listitem>
- <para>Test if an ST_Curve value is a ring.</para>
-
- <note>
- <para>SQL-MM defines the result of ST_IsRing(NULL) to be 0,
- while PostGIS returns NULL.</para>
- </note>
-
- <para>SQL-MM 3: 7.1.6</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsSimple</term>
-
- <listitem>
- <para>Test if an ST_Geometry value has no anomalous geometric
- points, such as self intersection or self tangency.</para>
-
- <note>
- <para>SQL-MM defines the result of ST_IsSimple(NULL) to be 0,
- while PostGIS returns NULL.</para>
- </note>
-
- <para>SQL-MM 3: 5.1.8</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_IsValid</term>
-
- <listitem>
- <para>Test if an ST_Geometry value is well formed.</para>
-
- <note>
- <para>SQL-MM defines the result of ST_IsValid(NULL) to be 0,
- while PostGIS returns NULL.</para>
- </note>
-
- <para>SQL-MM defines the result of ST_IsValid(NULL) to be 1</para>
-
- <para>SQL-MM 3: 5.1.9</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Length</term>
-
- <listitem>
- <para>Return the length measurement of an ST_Curve or
- ST_MultiCurve value.</para>
-
- <para>SQL-MM 3: 7.1.2, 9.3.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineFromText</term>
-
- <listitem>
- <para>Return a specified ST_LineString value.</para>
-
- <para>SQL-MM 3: 7.2.8</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_LineFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_LineString value.</para>
-
- <para>SQL-MM 3: 7.2.9</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MLineFromText</term>
-
- <listitem>
- <para>Return a specified ST_MultiLineString value.</para>
-
- <para>SQL-MM 3: 9.4.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MLineFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_MultiLineString value.</para>
-
- <para>SQL-MM 3: 9.4.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPointFromText</term>
-
- <listitem>
- <para>Return a specified ST_MultiPoint value.</para>
-
- <para>SQL-MM 3: 9.2.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPointFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_MultiPoint value.</para>
-
- <para>SQL-MM 3: 9.2.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPolyFromText</term>
-
- <listitem>
- <para>Return a specified ST_MultiPolygon value.</para>
-
- <para>SQL-MM 3: 9.6.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_MPolyFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_MultiPolygon value.</para>
-
- <para>SQL-MM 3: 9.6.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumGeometries</term>
-
- <listitem>
- <para>Return the number of geometries in an ST_GeomCollection.</para>
-
- <para>SQL-MM 3: 9.1.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumInteriorRing</term>
-
- <listitem>
- <para>Return the number of interior rings in an ST_Surface.</para>
-
- <para>SQL-MM 3: 8.2.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_NumPoints</term>
-
- <listitem>
- <para>Return the number of points in an ST_LineString or
- ST_CircularString value.</para>
-
- <para>SQL-MM 3: 7.2.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_OrderingEquals</term>
-
- <listitem>
- <para>ST_OrderingEquals compares two geometries and t (TRUE) if
- the geometries are equal and the coordinates are in the same
- order; otherwise it returns f (FALSE).</para>
-
- <note>
- <para>This function is implemented as per the ArcSDE SQL
- specification rather than SQL-MM.
- http://edndoc.esri.com/arcsde/9.1/sql_api/sqlapi3.htm#ST_OrderingEquals</para>
- </note>
-
- <para>SQL-MM 3: 5.1.43</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Overlaps</term>
-
- <listitem>
- <para>Test if an ST_Geometry value spatially overlays another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.32</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Perimeter</term>
-
- <listitem>
- <para>Return the length measurement of the boundary of an
- ST_Surface or ST_MultiRSurface value.</para>
-
- <para>SQL-MM 3: 8.1.3, 9.5.4</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Point</term>
-
- <listitem>
- <para>Returns an ST_Point with the given coordinate values.</para>
-
- <para>SQL-MM 3: 6.1.2</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointFromText</term>
-
- <listitem>
- <para>Return a specified ST_Point value.</para>
-
- <para>SQL-MM 3: 6.1.8</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_Point value.</para>
-
- <para>SQL-MM 3: 6.1.9</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointN</term>
-
- <listitem>
- <para>Return the specified ST_Point value in an ST_LineString or
- ST_CircularString</para>
-
- <para>SQL-MM 3: 7.2.5, 7.3.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PointOnSurface</term>
-
- <listitem>
- <para>Return an ST_Point value guaranteed to spatially intersect
- the ST_Surface or ST_MultiSurface value.</para>
-
- <para>SQL-MM 3: 8.1.5, 9.5.6</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolyFromText</term>
-
- <listitem>
- <para>Return a specified ST_Polygon value.</para>
-
- <para>SQL-MM 3: 8.3.6</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_PolyFromWKB</term>
-
- <listitem>
- <para>Return a specified ST_Polygon value.</para>
-
- <para>SQL-MM 3: 8.3.7</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Polygon</term>
-
- <listitem>
- <para>Return a polygon build from the specified linestring and
- SRID.</para>
-
- <para>SQL-MM 3: 8.3.2</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Relate</term>
-
- <listitem>
- <para>Test if an ST_Geometry value is spatially related to another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.25</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SRID</term>
-
- <listitem>
- <para>Return the spatial reference system identifier of the
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.5</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_StartPoint</term>
-
- <listitem>
- <para>Return an ST_Point value that is the start point of an
- ST_Curve value.</para>
-
- <para>SQL-MM 3: 7.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_SymDifference</term>
-
- <listitem>
- <para>Return an ST_Geometry value that represents the point set
- symmetric difference of two ST_Geometry values.</para>
-
- <para>SQL-MM 3: 5.1.21</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Touches</term>
-
- <listitem>
- <para>Test if an ST_Geometry value spatially touches another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.28</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Transform</term>
-
- <listitem>
- <para>Return an ST_Geometry value transformed to the specified
- spatial reference system.</para>
-
- <para>SQL-MM 3: 5.1.6</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Union</term>
-
- <listitem>
- <para>Return an ST_Geometry value that represents the point set
- union of two ST_Geometry values.</para>
-
- <para>SQL-MM 3: 5.1.19</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Within</term>
-
- <listitem>
- <para>Test if an ST_Geometry value is spatially within another
- ST_Geometry value.</para>
-
- <para>SQL-MM 3: 5.1.30</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_WKBToSQL</term>
-
- <listitem>
- <para>Return an ST_Geometry value for a given well-known binary
- representation.</para>
-
- <para>SQL-MM 3: 5.1.36</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_WKTToSQL</term>
-
- <listitem>
- <para>Return an ST_Geometry value for a given well-known text
- representation.</para>
-
- <para>SQL-MM 3: 5.1.34</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_X</term>
-
- <listitem>
- <para>Returns the x coordinate value of an ST_Point value.</para>
-
- <para>SQL-MM 3: 6.1.3</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>ST_Y</term>
-
- <listitem>
- <para>Returns the y coordinate value of an ST_Point value.</para>
-
- <para>SQL-MM 3: 6.1.4</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1>
- <title>ArcSDE Functions</title>
-
- <para>Additional functions have been added to improve support for an
- ArcSDE style interface.</para>
-
- <variablelist>
- <varlistentry>
- <term>SE_EnvelopesIntersect</term>
-
- <listitem>
- <para>Returns t (TRUE) if the envelopes of two geometries
- intersect; otherwise, it returns f (FALSE).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_Is3d</term>
-
- <listitem>
- <para>Test if a geometry value has z coordinate values.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_IsMeasured</term>
-
- <listitem>
- <para>Test if a geometry value has m coordinate values.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_LocateAlong</term>
-
- <listitem>
- <para>Return a derived geometry collection value with elements
- that match the specified measur.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_LocateBetween</term>
-
- <listitem>
- <para>Return a derived geometry collection value with elements
- that match the specified range of measures inclusively.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_M</term>
-
- <listitem>
- <para>Returns the m coordinate value of an ST_Point value.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SE_Z</term>
-
- <listitem>
- <para>Returns the z coordinate value of an ST_Point value</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
- </chapter>
-
- <chapter>
- <title>Reporting Problems</title>
- <sect1>
- <title>Reporting Software Bugs</title>
-
- <para>Reporting bugs effectively is a fundamental way to help PostGIS
- development. The most effective bug report is that enabling PostGIS
- developers to reproduce it, so it would ideally contain a script
- triggering it and every information regarding the environment in which it
- was detected. Good enough info can be extracted running <code>SELECT
- postgis_full_version()</code> [for postgis] and <code>SELECT version()</code>
- [for postgresql].</para>
-
- <para>If you aren't using the latest release, it's worth taking a look
- at its <ulink url="http://postgis.refractions.net/CHANGES.txt">release
- changelog</ulink> first, to find out if your bug has already been fixed.</para>
-
- <para>Using the <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS
- bug tracker</ulink> will ensure your reports are not discarded, and will
- keep you informed on its handling process. Before reporting a new bug
- please query the database to see if it is a known one, and if it is please
- add any new information you have about it.</para>
-
- <para>You might want to read Simon Tatham's paper about <ulink
- url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
- Bugs Effectively</ulink> before filing a new report.</para>
- </sect1>
- <sect1>
- <title>Reporting Documentation Issues</title>
-
- <para>The documentation should accurately reflect the features and
- behavior of the software. If it doesn't, it could be because of a software bug or
- because the documentation is in error or deficient.</para>
-
- <para>Documentation issues can also be reported to the
- <ulink url="http://code.google.com/p/postgis/issues/list">PostGIS bug tracker</ulink>.</para>
-
- <para>If your revision is trivial, just describe it in a new bug tracker issue,
- being specific about its location in the documentation.</para>
-
- <para>If your changes are more extensive, a Subversion patch is definitely preferred.
- This is a four step process on Unix (assuming you already have
- <ulink url="http://subversion.tigris.org/">Subversion</ulink> installed):</para>
-
- <orderedlist>
- <listitem>
-
- <para>Check out a copy of PostGIS' Subversion trunk. On Unix, type:</para>
-
- <para><command>svn checkout http://svn.refractions.net/postgis/trunk/</command></para>
-
- <para>This will be stored in the directory ./trunk </para>
- </listitem>
- <listitem>
-
- <para>Make your changes to the documentation with your favorite text editor. On Unix, type (for example):</para>
-
- <para><command>vi trunk/doc/postgis.xml</command></para>
-
- <para>Note that the documentation is written in SGML rather than HTML,
- so if you are not familiar with it please follow the example of the rest of the documentation.</para>
-
- </listitem>
- <listitem>
-
- <para>Make a patch file containing the differences from the master copy of the documentation. On Unix, type:</para>
-
- <para><command>svn diff trunk/doc/postgis.xml > doc.patch</command></para>
-
- </listitem>
- <listitem>
-
- <para>Attach the patch to a new issue in bug tracker.</para>
-
- </listitem>
- </orderedlist>
-
- </sect1>
- </chapter>
-
- <appendix id="release_notes">
- <title>Appendix</title>
-
- <sect1>
- <title>Release Notes</title>
-
- <sect2>
- <title>Release 1.3.3</title>
- <para>Release date: 2008/04/12</para>
- <para>This release fixes bugs shp2pgsql, adds enhancements
- to SVG and KML support, adds a ST_SimplifyPreserveTopology
- function, makes the build more sensitive to GEOS versions,
- and fixes a handful of severe but rare failure cases.
- </para>
- </sect2>
-
- <sect2>
- <title>Release 1.3.2</title>
- <para>Release date: 2007/12/01</para>
- <para>This release fixes bugs in ST_EndPoint() and ST_Envelope,
- improves support for JDBC building and OS/X, and adds
- better support for GML output with ST_AsGML(), including
- GML3 output.</para>
- </sect2>
-
- <sect2>
- <title>Release 1.3.1</title>
- <para>Release date: 2007/08/13</para>
- <para>This release fixes some oversights in the previous release
- around version numbering, documentation, and tagging.</para>
- </sect2>
-
- <sect2>
- <title>Release 1.3.0</title>
- <para>Release date: 2007/08/09</para>
- <para>This release provides performance enhancements to the relational
- functions, adds new relational functions and begins the migration of
- our function names to the SQL-MM convension, using the spatial type
- (SP) prefix.</para>
- <sect3>
- <title>Added Functionality</title>
- <para>JDBC: Added Hibernate Dialect (thanks to Norman Barker)</para>
- <para>Added ST_Covers and ST_CoveredBy relational functions.
- Description and justification of these functions can be found at
- http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html</para>
- <para>Added ST_DWithin relational function.</para>
- </sect3>
- <sect3>
- <title>Performance Enhancements</title>
- <para>Added cached and indexed point-in-polygon short-circuits
- for the functions ST_Contains, ST_Intersects, ST_Within and
- ST_Disjoint</para>
- <para>Added inline index support for relational functions
- (except ST_Disjoint)</para>
- </sect3>
- <sect3>
- <title>Other Changes</title>
- <para>Extended curved geometry support into the geometry accessor
- and some processing functions</para>
- <para>Began migration of functions to the SQL-MM naming convension;
- using a spatial type (ST) prefix.</para>
- <para>Added initial support for PostgreSQL 8.3</para>
- </sect3>
- </sect2>
- <sect2>
- <title>Release 1.2.1</title>
-
- <para>Release date: 2007/01/11</para>
-
- <para>This release provides bug fixes in PostgreSQL 8.2 support and
- some small performance enhancements.</para>
-
- <sect3>
- <title>Changes</title>
-
- <para>Fixed point-in-polygon shortcut bug in Within().</para>
-
- <para>Fixed PostgreSQL 8.2 NULL handling for indexes.</para>
-
- <para>Updated RPM spec files.</para>
-
- <para>Added short-circuit for Transform() in no-op case.</para>
-
- <para>JDBC: Fixed JTS handling for multi-dimensional geometries
- (thanks to Thomas Marti for hint and partial patch). Additionally,
- now JavaDoc is compiled and packaged. Fixed classpath problems with
- GCJ. Fixed pgjdbc 8.2 compatibility, losing support for jdk 1.3 and
- older.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.2.0</title>
-
- <para>Release date: 2006/12/08</para>
-
- <para>This release provides type definitions along with
- serialization/deserialization capabilities for SQL-MM defined curved
- geometries, as well as performance enhancements.</para>
-
- <sect3>
- <title>Changes</title>
-
- <para>Added curved geometry type support for
- serialization/deserialization</para>
-
- <para>Added point-in-polygon shortcircuit to the Contains and Within
- functions to improve performance for these cases.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.6</title>
-
- <para>Release date: 2006/11/02</para>
-
- <para>This is a bugfix release, in particular fixing a critical error
- with GEOS interface in 64bit systems. Includes an updated of the SRS
- parameters and an improvement in reprojections (take Z in
- consideration). Upgrade is <emphasis>encouraged</emphasis>.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>fixed CAPI change that broke 64-bit platforms</para>
-
- <para>loader/dumper: fixed regression tests and usage output</para>
-
- <para>Fixed setSRID() bug in JDBC, thanks to Thomas Marti</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>use Z ordinate in reprojections</para>
-
- <para>spatial_ref_sys.sql updated to EPSG 6.11.1</para>
-
- <para>Simplified Version.config infrastructure to use a single pack
- of version variables for everything.</para>
-
- <para>Include the Version.config in loader/dumper USAGE messages</para>
-
- <para>Replace hand-made, fragile JDBC version parser with Properties</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.5</title>
-
- <para>Release date: 2006/10/13</para>
-
- <para>This is an bugfix release, including a critical segfault on
- win32. Upgrade is <emphasis>encouraged</emphasis>.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fixed MingW link error that was causing pgsql2shp to segfault
- on Win32 when compiled for PostgreSQL 8.2</para>
-
- <para>fixed nullpointer Exception in Geometry.equals() method in
- Java</para>
-
- <para>Added EJB3Spatial.odt to fulfill the GPL requirement of
- distributing the "preferred form of modification"</para>
-
- <para>Removed obsolete synchronization from JDBC Jts code.</para>
-
- <para>Updated heavily outdated README files for shp2pgsql/pgsql2shp
- by merging them with the manpages.</para>
-
- <para>Fixed version tag in jdbc code that still said "1.1.3"
- in the "1.1.4" release.</para>
- </sect3>
-
- <sect3>
- <title>New Features</title>
-
- <para>Added -S option for non-multi geometries to shp2pgsql</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.4</title>
-
- <para>Release date: 2006/09/27</para>
-
- <para>This is an bugfix release including some improvements in the
- Java interface. Upgrade is <emphasis>encouraged</emphasis>.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fixed support for PostgreSQL 8.2</para>
-
- <para>Fixed bug in collect() function discarding SRID of input</para>
-
- <para>Added SRID match check in MakeBox2d and MakeBox3d</para>
-
- <para>Fixed regress tests to pass with GEOS-3.0.0</para>
-
- <para>Improved pgsql2shp run concurrency.</para>
- </sect3>
-
- <sect3>
- <title>Java changes</title>
-
- <para>reworked JTS support to reflect new upstream JTS
- developers' attitude to SRID handling. Simplifies code and drops
- build depend on GNU trove.</para>
-
- <para>Added EJB2 support generously donated by the "Geodetix
- s.r.l. Company" http://www.geodetix.it/</para>
-
- <para>Added EJB3 tutorial / examples donated by Norman Barker
- <nbarker@ittvis.com></para>
-
- <para>Reorganized java directory layout a little.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.3</title>
-
- <para>Release date: 2006/06/30</para>
-
- <para>This is an bugfix release including also some new
- functionalities (most notably long transaction support) and
- portability enhancements. Upgrade is <emphasis>encouraged</emphasis>.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes / correctness</title>
-
- <para>BUGFIX in distance(poly,poly) giving wrong results.</para>
-
- <para>BUGFIX in pgsql2shp successful return code.</para>
-
- <para>BUGFIX in shp2pgsql handling of MultiLine WKT.</para>
-
- <para>BUGFIX in affine() failing to update bounding box.</para>
-
- <para>WKT parser: forbidden construction of multigeometries with
- EMPTY elements (still supported for GEOMETRYCOLLECTION).</para>
- </sect3>
-
- <sect3>
- <title>New functionalities</title>
-
- <para>NEW Long Transactions support.</para>
-
- <para>NEW DumpRings() function.</para>
-
- <para>NEW AsHEXEWKB(geom, XDR|NDR) function.</para>
- </sect3>
-
- <sect3>
- <title>JDBC changes</title>
-
- <para>Improved regression tests: MultiPoint and scientific ordinates</para>
-
- <para>Fixed some minor bugs in jdbc code</para>
-
- <para>Added proper accessor functions for all fields in preparation
- of making those fields private later</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>NEW regress test support for loader/dumper.</para>
-
- <para>Added --with-proj-libdir and --with-geos-libdir configure
- switches.</para>
-
- <para>Support for build Tru64 build.</para>
-
- <para>Use Jade for generating documentation.</para>
-
- <para>Don't link pgsql2shp to more libs then required.</para>
-
- <para>Initial support for PostgreSQL 8.2.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.2</title>
-
- <para>Release date: 2006/03/30</para>
-
- <para>This is an bugfix release including some new functions and
- portability enhancements. Upgrade is <emphasis>encouraged</emphasis>.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>BUGFIX in SnapToGrid() computation of output bounding box</para>
-
- <para>BUGFIX in EnforceRHR()</para>
-
- <para>jdbc2 SRID handling fixes in JTS code</para>
-
- <para>Fixed support for 64bit archs</para>
- </sect3>
-
- <sect3>
- <title>New functionalities</title>
-
- <para>Regress tests can now be run *before* postgis installation</para>
-
- <para>New affine() matrix transformation functions</para>
-
- <para>New rotate{,X,Y,Z}() function</para>
-
- <para>Old translating and scaling functions now use affine()
- internally</para>
-
- <para>Embedded access control in estimated_extent() for builds
- against pgsql >= 8.0.0</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>More portable ./configure script</para>
-
- <para>Changed ./run_test script to have more sane default behaviour</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.1</title>
-
- <para>Release date: 2006/01/23</para>
-
- <para>This is an important Bugfix release, upgrade is
- <emphasis>highly recommended</emphasis>. Previous version contained a
- bug in postgis_restore.pl preventing <link linkend="hard_upgrade">hard
- upgrade</link> procedure to complete and a bug in GEOS-2.2+ connector
- preventing GeometryCollection objects to be used in topological
- operations.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later follow the
- <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fixed a premature exit in postgis_restore.pl</para>
-
- <para>BUGFIX in geometrycollection handling of GEOS-CAPI connector</para>
-
- <para>Solaris 2.7 and MingW support improvements</para>
-
- <para>BUGFIX in line_locate_point()</para>
-
- <para>Fixed handling of postgresql paths</para>
-
- <para>BUGFIX in line_substring()</para>
-
- <para>Added support for localized cluster in regress tester</para>
- </sect3>
-
- <sect3>
- <title>New functionalities</title>
-
- <para>New Z and M interpolation in line_substring()</para>
-
- <para>New Z and M interpolation in line_interpolate_point()</para>
-
- <para>added NumInteriorRing() alias due to OpenGIS ambiguity</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.1.0</title>
-
- <para>Release date: 2005/12/21</para>
-
- <para>This is a Minor release, containing many improvements and new
- things. Most notably: build procedure greatly simplified; transform()
- performance drastically improved; more stable GEOS connectivity (CAPI
- support); lots of new functions; draft topology support.</para>
-
- <para>It is <emphasis>highly recommended</emphasis> that you upgrade
- to GEOS-2.2.x before installing PostGIS, this will ensure future GEOS
- upgrades won't require a rebuild of the PostGIS library.</para>
-
- <sect3>
- <title>Credits</title>
-
- <para>This release includes code from Mark Cave Ayland for caching
- of proj4 objects. Markus Schaber added many improvements in his
- JDBC2 code. Alex Bodnaru helped with PostgreSQL source dependency
- relief and provided Debian specfiles. Michael Fuhr tested new things
- on Solaris arch. David Techer and Gerald Fenoy helped testing GEOS
- C-API connector. Hartmut Tschauner provided code for the azimuth()
- function. Devrim GUNDUZ provided RPM specfiles. Carl Anderson helped
- with the new area building functions. See the <link
- linkend="credits">credits</link> section for more names.</para>
- </sect3>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later you
- <emphasis>DO NOT</emphasis> need a dump/reload. Simply sourcing the
- new lwpostgis_upgrade.sql script in all your existing databases will
- work. See the <link linkend="soft_upgrade">soft upgrade</link>
- chapter for more information.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>New functions</title>
-
- <para>scale() and transscale() companion methods to translate()</para>
-
- <para>line_substring()</para>
-
- <para>line_locate_point()</para>
-
- <para>M(point)</para>
-
- <para>LineMerge(geometry)</para>
-
- <para>shift_longitude(geometry)</para>
-
- <para>azimuth(geometry)</para>
-
- <para>locate_along_measure(geometry, float8)</para>
-
- <para>locate_between_measures(geometry, float8, float8)</para>
-
- <para>SnapToGrid by point offset (up to 4d support)</para>
-
- <para>BuildArea(any_geometry)</para>
-
- <para>OGC BdPolyFromText(linestring_wkt, srid)</para>
-
- <para>OGC BdMPolyFromText(linestring_wkt, srid)</para>
-
- <para>RemovePoint(linestring, offset)</para>
-
- <para>ReplacePoint(linestring, offset, point)</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fixed memory leak in polygonize()</para>
-
- <para>Fixed bug in lwgeom_as_anytype cast functions</para>
-
- <para>Fixed USE_GEOS, USE_PROJ and USE_STATS elements of
- postgis_version() output to always reflect library state.</para>
- </sect3>
-
- <sect3>
- <title>Function semantic changes</title>
-
- <para>SnapToGrid doesn't discard higher dimensions</para>
-
- <para>Changed Z() function to return NULL if requested dimension is
- not available</para>
- </sect3>
-
- <sect3>
- <title>Performance improvements</title>
-
- <para>Much faster transform() function, caching proj4 objects</para>
-
- <para>Removed automatic call to fix_geometry_columns() in
- AddGeometryColumns() and update_geometry_stats()</para>
- </sect3>
-
- <sect3>
- <title>JDBC2 works</title>
-
- <para>Makefile improvements</para>
-
- <para>JTS support improvements</para>
-
- <para>Improved regression test system</para>
-
- <para>Basic consistency check method for geometry collections</para>
-
- <para>Support for (Hex)(E)wkb</para>
-
- <para>Autoprobing DriverWrapper for HexWKB / EWKT switching</para>
-
- <para>fix compile problems in ValueSetter for ancient jdk releases.</para>
-
- <para>fix EWKT constructors to accept SRID=4711; representation</para>
-
- <para>added preliminary read-only support for java2d geometries</para>
- </sect3>
-
- <sect3>
- <title>Other new things</title>
-
- <para>Full autoconf-based configuration, with PostgreSQL source
- dependency relief</para>
-
- <para>GEOS C-API support (2.2.0 and higher)</para>
-
- <para>Initial support for topology modelling</para>
-
- <para>Debian and RPM specfiles</para>
-
- <para>New lwpostgis_upgrade.sql script</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>JTS support improvements</para>
-
- <para>Stricter mapping between DBF and SQL integer and string
- attributes</para>
-
- <para>Wider and cleaner regression test suite</para>
-
- <para>old jdbc code removed from release</para>
-
- <para>obsoleted direct use of postgis_proc_upgrade.pl</para>
-
- <para>scripts version unified with release version</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.6</title>
-
- <para>Release date: 2005/12/06</para>
-
- <para>Contains a few bug fixes and improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fixed palloc(0) call in collection deserializer (only gives
- problem with --enable-cassert)</para>
-
- <para>Fixed bbox cache handling bugs</para>
-
- <para>Fixed geom_accum(NULL, NULL) segfault</para>
-
- <para>Fixed segfault in addPoint()</para>
-
- <para>Fixed short-allocation in lwcollection_clone()</para>
-
- <para>Fixed bug in segmentize()</para>
-
- <para>Fixed bbox computation of SnapToGrid output</para>
- </sect3>
-
- <sect3>
- <title>Improvements</title>
-
- <para>Initial support for postgresql 8.2</para>
-
- <para>Added missing SRID mismatch checks in GEOS ops</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.5</title>
-
- <para>Release date: 2005/11/25</para>
-
- <para>Contains memory-alignment fixes in the library, a segfault fix
- in loader's handling of UTF8 attributes and a few improvements and
- cleanups.</para>
-
- <note>
- <para>Return code of shp2pgsql changed from previous releases to
- conform to unix standards (return 0 on success).</para>
- </note>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 or later you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>Fixed memory alignment problems</para>
-
- <para>Fixed computation of null values fraction in analyzer</para>
-
- <para>Fixed a small bug in the getPoint4d_p() low-level function</para>
-
- <para>Speedup of serializer functions</para>
-
- <para>Fixed a bug in force_3dm(), force_3dz() and force_4d()</para>
- </sect3>
-
- <sect3>
- <title>Loader changes</title>
-
- <para>Fixed return code of shp2pgsql</para>
-
- <para>Fixed back-compatibility issue in loader (load of null
- shapefiles)</para>
-
- <para>Fixed handling of trailing dots in dbf numerical attributes</para>
-
- <para>Segfault fix in shp2pgsql (utf8 encoding)</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>Schema aware postgis_proc_upgrade.pl, support for pgsql 7.2+</para>
-
- <para>New "Reporting Bugs" chapter in manual</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.4</title>
-
- <para>Release date: 2005/09/09</para>
-
- <para>Contains important bug fixes and a few improvements. In
- particular, it fixes a memory leak preventing successful build of GiST
- indexes for large spatial tables.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.3 you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
- and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
- the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of
- the 1.0.3 release notes chapter.</para>
-
- <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
- linkend="hard_upgrade">hard upgrade</link>.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Memory leak plugged in GiST indexing</para>
-
- <para>Segfault fix in transform() handling of proj4 errors</para>
-
- <para>Fixed some proj4 texts in spatial_ref_sys (missing +proj)</para>
-
- <para>Loader: fixed string functions usage, reworked NULL objects
- check, fixed segfault on MULTILINESTRING input.</para>
-
- <para>Fixed bug in MakeLine dimension handling</para>
-
- <para>Fixed bug in translate() corrupting output bounding box</para>
- </sect3>
-
- <sect3>
- <title>Improvements</title>
-
- <para>Documentation improvements</para>
-
- <para>More robust selectivity estimator</para>
-
- <para>Minor speedup in distance()</para>
-
- <para>Minor cleanups</para>
-
- <para>GiST indexing cleanup</para>
-
- <para>Looser syntax acceptance in box3d parser</para>
- </sect3>
- </sect2>
-
- <sect2 id="rel_1.0.3_upgrading">
- <title>Release 1.0.3</title>
-
- <para>Release date: 2005/08/08</para>
-
- <para>Contains some bug fixes - <emphasis>including a severe one
- affecting correctness of stored geometries</emphasis> - and a few
- improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>Due to a bug in a bounding box computation routine, the
- upgrade procedure requires special attention, as bounding boxes
- cached in the database could be incorrect.</para>
-
- <para>An <link linkend="hard_upgrade">hard upgrade</link> procedure
- (dump/reload) will force recomputation of all bounding boxes (not
- included in dumps). This is <emphasis>required</emphasis> if
- upgrading from releases prior to 1.0.0RC6.</para>
-
- <para>If you are upgrading from versions 1.0.0RC6 or up, this
- release includes a perl script (utils/rebuild_bbox_caches.pl) to
- force recomputation of geometries' bounding boxes and invoke all
- operations required to propagate eventual changes in them (geometry
- statistics update, reindexing). Invoke the script after a make
- install (run with no args for syntax help). Optionally run
- utils/postgis_proc_upgrade.pl to refresh postgis procedures and
- functions signatures (see <link linkend="soft_upgrade">Soft upgrade</link>).</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Severe bugfix in lwgeom's 2d bounding box computation</para>
-
- <para>Bugfix in WKT (-w) POINT handling in loader</para>
-
- <para>Bugfix in dumper on 64bit machines</para>
-
- <para>Bugfix in dumper handling of user-defined queries</para>
-
- <para>Bugfix in create_undef.pl script</para>
- </sect3>
-
- <sect3>
- <title>Improvements</title>
-
- <para>Small performance improvement in canonical input function</para>
-
- <para>Minor cleanups in loader</para>
-
- <para>Support for multibyte field names in loader</para>
-
- <para>Improvement in the postgis_restore.pl script</para>
-
- <para>New rebuild_bbox_caches.pl util script</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.2</title>
-
- <para>Release date: 2005/07/04</para>
-
- <para>Contains a few bug fixes and improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.0RC6 or up you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>Upgrading from older releases requires a dump/reload. See the
- <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Bug fixes</title>
-
- <para>Fault tolerant btree ops</para>
-
- <para>Memory leak plugged in pg_error</para>
-
- <para>Rtree index fix</para>
-
- <para>Cleaner build scripts (avoided mix of CFLAGS and CXXFLAGS)</para>
- </sect3>
-
- <sect3>
- <title>Improvements</title>
-
- <para>New index creation capabilities in loader (-I switch)</para>
-
- <para>Initial support for postgresql 8.1dev</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.1</title>
-
- <para>Release date: 2005/05/24</para>
-
- <para>Contains a few bug fixes and some improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.0RC6 or up you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>Upgrading from older releases requires a dump/reload. See the
- <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX in 3d computation of length_spheroid()</para>
-
- <para>BUGFIX in join selectivity estimator</para>
- </sect3>
-
- <sect3>
- <title>Other changes/additions</title>
-
- <para>BUGFIX in shp2pgsql escape functions</para>
-
- <para>better support for concurrent postgis in multiple schemas</para>
-
- <para>documentation fixes</para>
-
- <para>jdbc2: compile with "-target 1.2 -source 1.2" by
- default</para>
-
- <para>NEW -k switch for pgsql2shp</para>
-
- <para>NEW support for custom createdb options in postgis_restore.pl</para>
-
- <para>BUGFIX in pgsql2shp attribute names unicity enforcement</para>
-
- <para>BUGFIX in Paris projections definitions</para>
-
- <para>postgis_restore.pl cleanups</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0</title>
-
- <para>Release date: 2005/04/19</para>
-
- <para>Final 1.0.0 release. Contains a few bug fixes, some improvements
- in the loader (most notably support for older postgis versions), and
- more docs.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.0RC6 you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>Upgrading from any other precedent release requires a
- dump/reload. See the <link linkend="upgrading">upgrading</link>
- chapter for more informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX in transform() releasing random memory address</para>
-
- <para>BUGFIX in force_3dm() allocating less memory then required</para>
-
- <para>BUGFIX in join selectivity estimator (defaults, leaks,
- tuplecount, sd)</para>
- </sect3>
-
- <sect3>
- <title>Other changes/additions</title>
-
- <para>BUGFIX in shp2pgsql escape of values starting with tab or
- single-quote</para>
-
- <para>NEW manual pages for loader/dumper</para>
-
- <para>NEW shp2pgsql support for old (HWGEOM) postgis versions</para>
-
- <para>NEW -p (prepare) flag for shp2pgsql</para>
-
- <para>NEW manual chapter about OGC compliancy enforcement</para>
-
- <para>NEW autoconf support for JTS lib</para>
-
- <para>BUGFIX in estimator testers (support for LWGEOM and schema
- parsing)</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC6</title>
-
- <para>Release date: 2005/03/30</para>
-
- <para>Sixth release candidate for 1.0.0. Contains a few bug fixes and
- cleanups.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>You need a dump/reload to upgrade from precedent releases. See
- the <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX in multi()</para>
-
- <para>early return [when noop] from multi()</para>
- </sect3>
-
- <sect3>
- <title>Scripts changes</title>
-
- <para>dropped {x,y}{min,max}(box2d) functions</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>BUGFIX in postgis_restore.pl scrip</para>
-
- <para>BUGFIX in dumper's 64bit support</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC5</title>
-
- <para>Release date: 2005/03/25</para>
-
- <para>Fifth release candidate for 1.0.0. Contains a few bug fixes and
- a improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>If you are upgrading from release 1.0.0RC4 you
- <emphasis>DO NOT</emphasis> need a dump/reload.</para>
-
- <para>Upgrading from any other precedent release requires a
- dump/reload. See the <link linkend="upgrading">upgrading</link>
- chapter for more informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX (segfaulting) in box3d computation (yes, another!).</para>
-
- <para>BUGFIX (segfaulting) in estimated_extent().</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>Small build scripts and utilities refinements.</para>
-
- <para>Additional performance tips documented.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC4</title>
-
- <para>Release date: 2005/03/18</para>
-
- <para>Fourth release candidate for 1.0.0. Contains bug fixes and a few
- improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>You need a dump/reload to upgrade from precedent releases. See
- the <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX (segfaulting) in geom_accum().</para>
-
- <para>BUGFIX in 64bit architectures support.</para>
-
- <para>BUGFIX in box3d computation function with collections.</para>
-
- <para>NEW subselects support in selectivity estimator.</para>
-
- <para>Early return from force_collection.</para>
-
- <para>Consistency check fix in SnapToGrid().</para>
-
- <para>Box2d output changed back to 15 significant digits.</para>
- </sect3>
-
- <sect3>
- <title>Scripts changes</title>
-
- <para>NEW distance_sphere() function.</para>
-
- <para>Changed get_proj4_from_srid implementation to use PL/PGSQL
- instead of SQL.</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>BUGFIX in loader and dumper handling of MultiLine shapes</para>
-
- <para>BUGFIX in loader, skipping all but first hole of polygons.</para>
-
- <para>jdbc2: code cleanups, Makefile improvements</para>
-
- <para>FLEX and YACC variables set *after* pgsql Makefile.global is
- included and only if the pgsql *stripped* version evaluates to the
- empty string</para>
-
- <para>Added already generated parser in release</para>
-
- <para>Build scripts refinements</para>
-
- <para>improved version handling, central Version.config</para>
-
- <para>improvements in postgis_restore.pl</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC3</title>
-
- <para>Release date: 2005/02/24</para>
-
- <para>Third release candidate for 1.0.0. Contains many bug fixes and
- improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>You need a dump/reload to upgrade from precedent releases. See
- the <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX in transform(): missing SRID, better error handling.</para>
-
- <para>BUGFIX in memory alignment handling</para>
-
- <para>BUGFIX in force_collection() causing mapserver connector
- failures on simple (single) geometry types.</para>
-
- <para>BUGFIX in GeometryFromText() missing to add a bbox cache.</para>
-
- <para>reduced precision of box2d output.</para>
-
- <para>prefixed DEBUG macros with PGIS_ to avoid clash with pgsql one</para>
-
- <para>plugged a leak in GEOS2POSTGIS converter</para>
-
- <para>Reduced memory usage by early releasing query-context palloced
- one.</para>
- </sect3>
-
- <sect3>
- <title>Scripts changes</title>
-
- <para>BUGFIX in 72 index bindings.</para>
-
- <para>BUGFIX in probe_geometry_columns() to work with PG72 and
- support multiple geometry columns in a single table</para>
-
- <para>NEW bool::text cast</para>
-
- <para>Some functions made IMMUTABLE from STABLE, for performance
- improvement.</para>
- </sect3>
-
- <sect3>
- <title>JDBC changes</title>
-
- <para>jdbc2: small patches, box2d/3d tests, revised docs and
- license.</para>
-
- <para>jdbc2: bug fix and testcase in for pgjdbc 8.0 type
- autoregistration</para>
-
- <para>jdbc2: Removed use of jdk1.4 only features to enable build
- with older jdk releases.</para>
-
- <para>jdbc2: Added support for building against pg72jdbc2.jar</para>
-
- <para>jdbc2: updated and cleaned makefile</para>
-
- <para>jdbc2: added BETA support for jts geometry classes</para>
-
- <para>jdbc2: Skip known-to-fail tests against older PostGIS servers.</para>
-
- <para>jdbc2: Fixed handling of measured geometries in EWKT.</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>new performance tips chapter in manual</para>
-
- <para>documentation updates: pgsql72 requirement, lwpostgis.sql</para>
-
- <para>few changes in autoconf</para>
-
- <para>BUILDDATE extraction made more portable</para>
-
- <para>fixed spatial_ref_sys.sql to avoid vacuuming the whole
- database.</para>
-
- <para>spatial_ref_sys: changed Paris entries to match the ones
- distributed with 0.x.</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC2</title>
-
- <para>Release date: 2005/01/26</para>
-
- <para>Second release candidate for 1.0.0 containing bug fixes and a
- few improvements.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>You need a dump/reload to upgrade from precedent releases. See
- the <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Library changes</title>
-
- <para>BUGFIX in pointarray box3d computation</para>
-
- <para>BUGFIX in distance_spheroid definition</para>
-
- <para>BUGFIX in transform() missing to update bbox cache</para>
-
- <para>NEW jdbc driver (jdbc2)</para>
-
- <para>GEOMETRYCOLLECTION(EMPTY) syntax support for backward
- compatibility</para>
-
- <para>Faster binary outputs</para>
-
- <para>Stricter OGC WKB/WKT constructors</para>
- </sect3>
-
- <sect3>
- <title>Scripts changes</title>
-
- <para>More correct STABLE, IMMUTABLE, STRICT uses in lwpostgis.sql</para>
-
- <para>stricter OGC WKB/WKT constructors</para>
- </sect3>
-
- <sect3>
- <title>Other changes</title>
-
- <para>Faster and more robust loader (both i18n and not)</para>
-
- <para>Initial autoconf script</para>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Release 1.0.0RC1</title>
-
- <para>Release date: 2005/01/13</para>
-
- <para>This is the first candidate of a major postgis release, with
- internal storage of postgis types redesigned to be smaller and faster
- on indexed queries.</para>
-
- <sect3>
- <title>Upgrading</title>
-
- <para>You need a dump/reload to upgrade from precedent releases. See
- the <link linkend="upgrading">upgrading</link> chapter for more
- informations.</para>
- </sect3>
-
- <sect3>
- <title>Changes</title>
-
- <para>Faster canonical input parsing.</para>
-
- <para>Lossless canonical output.</para>
-
- <para>EWKB Canonical binary IO with PG>73.</para>
-
- <para>Support for up to 4d coordinates, providing lossless
- shapefile->postgis->shapefile conversion.</para>
-
- <para>New function: UpdateGeometrySRID(), AsGML(), SnapToGrid(),
- ForceRHR(), estimated_extent(), accum().</para>
-
- <para>Vertical positioning indexed operators.</para>
-
- <para>JOIN selectivity function.</para>
-
- <para>More geometry constructors / editors.</para>
-
- <para>PostGIS extension API.</para>
-
- <para>UTF8 support in loader.</para>
- </sect3>
- </sect2>
- </sect1>
- </appendix>
+ &introduction;
+ &installation;
+ &faq;
+ &using_postgis;
+ &performance_tips;
+ &reference;
+ &reporting;
+ &release_notes;
+
</book>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>PostGIS Reference</title>
+
+ <para>The functions given below are the ones which a user of PostGIS is
+ likely to need. There are other functions which are required support
+ functions to the PostGIS objects which are not of use to a general
+ user.</para>
+
+ <note>
+ <para>PostGIS has begun a transition from the existing naming convention
+ to an SQL-MM-centric convention. As a result, most of the functions that
+ you know and love have been renamed using the standard spatial type (ST)
+ prefix. Previous functions are still available, though are not listed in
+ this document where updated functions are equivalent. These will be
+ deprecated in a future release.</para>
+ </note>
+
+ <sect1>
+ <title>OpenGIS Functions</title>
+
+ <sect2>
+ <title>Management Functions</title>
+
+ <variablelist>
+ <varlistentry id="AddGeometryColumn">
+ <term>AddGeometryColumn(varchar, varchar, varchar, integer, varchar,
+ integer)</term>
+
+ <listitem>
+ <para>Syntax: AddGeometryColumn(<schema_name>,
+ <table_name>, <column_name>, <srid>,
+ <type>, <dimension>). Adds a geometry column to an
+ existing table of attributes. The <varname>schema_name</varname>
+ is the name of the table schema (unused for pre-schema PostgreSQL
+ installations). The <varname>srid</varname> must be an integer
+ value reference to an entry in the SPATIAL_REF_SYS table. The
+ <varname>type</varname> must be an uppercase string corresponding
+ to the geometry type, eg, 'POLYGON' or 'MULTILINESTRING'.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DropGeometryColumn(varchar, varchar, varchar)</term>
+
+ <listitem>
+ <para>Syntax: DropGeometryColumn(<schema_name>,
+ <table_name>, <column_name>). Remove a geometry column
+ from a spatial table. Note that schema_name will need to match the
+ f_schema_name field of the table's row in the geometry_columns
+ table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SetSRID(geometry, integer)</term>
+
+ <listitem>
+ <para>Set the SRID on a geometry to a particular integer value.
+ Useful in constructing bounding boxes for queries.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Relationship Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_Distance(geometry, geometry)</term>
+
+ <listitem>
+ <para>Return the cartesian distance between two geometries in
+ projected units. Does not use indexes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_DWithin(geometry, geometry, float)</term>
+
+ <listitem>
+ <para>Returns true if geometries are within the specified distance
+ of one another. Uses indexes if available.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Equals(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the given Geometries are "spatially
+ equal". Use this for a 'better' answer than '='.
+ equals('LINESTRING(0 0, 10 10)','LINESTRING(0 0, 5 5, 10 10)') is
+ true.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>OGC SPEC s2.1.1.2</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Disjoint(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries are "spatially
+ disjoint".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 //s2.1.13.3 - a.Relate(b,
+ 'FF*FF****')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Intersects(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries "spatially
+ intersect".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Intersects.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 //s2.1.13.3 - Intersects(g1, g2 ) -->
+ Not (Disjoint(g1, g2 ))</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Touches(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries "spatially touch".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Touches.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3- a.Touches(b) -> (I(a)
+ intersection I(b) = {empty set} ) and (a intersection b) not
+ empty</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Crosses(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries "spatially cross".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Crosses.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
+ 'T*T******')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Within(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if Geometry A is "spatially within"
+ Geometry B. A has to be completely inside B.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Within.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - a.Relate(b,
+ 'T*F**F***')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Overlaps(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries "spatially
+ overlap".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Overlaps.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Contains(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if Geometry A "spatially contains" Geometry
+ B.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Contains.</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - same as within(geometry B,
+ geometry A)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Covers(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if no point in Geometry B is outside
+ Geometry A</para>
+
+ <para>Refer to
+ http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html
+ for an explanation of the need of this function.</para>
+
+ <para>This function call will automatically include a bounding box
+ comparison that will make use of any indexes that are available on
+ the geometries. To avoid index use, use the function
+ _ST_Covers.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_CoveredBy(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if no point in Geometry A is outside
+ Geometry B</para>
+
+ <para>Refer to
+ http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html
+ for an explaination of the need of this function.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Intersects(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if the Geometries "spatially
+ intersect".</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3 - NOT disjoint(geometry,
+ geometry)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Relate(geometry, geometry,
+ intersectionPatternMatrix)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is spatially related to
+ anotherGeometry, by testing for intersections between the
+ Interior, Boundary and Exterior of the two geometries as specified
+ by the values in the intersectionPatternMatrix.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>NOTE: this is the "allowable" version that returns a
+ boolean, not an integer.</para>
+
+ <para>OGC SPEC s2.1.1.2 // s2.1.13.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Relate(geometry, geometry)</term>
+
+ <listitem>
+ <para>returns the DE-9IM (dimensionally extended nine-intersection
+ matrix)</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>not in OGC spec, but implied. see s2.1.13.2</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Processing Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_Centroid(geometry)</term>
+
+ <listitem>
+ <para>Returns the centroid of the geometry as a point.</para>
+
+ <para>Computation will be more accurate if performed by the GEOS
+ module (enabled at compile time).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Area(geometry)</term>
+
+ <listitem>
+ <para>Returns the area of the geometry if it is a polygon or
+ multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Length(geometry)</term>
+
+ <listitem>
+ <para>The length of this Curve in its associated spatial
+ reference.</para>
+
+ <para>synonym for length2d()</para>
+
+ <para>OGC SPEC 2.1.5.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointOnSurface(geometry)</term>
+
+ <listitem>
+ <para>Return a Point guaranteed to lie on the surface</para>
+
+ <para>Implemented using GEOS</para>
+
+ <para>OGC SPEC 3.2.14.2 and 3.2.18.2 -</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Boundary(geometry)</term>
+
+ <listitem>
+ <para>Returns the closure of the combinatorial boundary of this
+ Geometry. The combinatorial boundary is defined as described in
+ section 3.12.3.2 of the OGC SPEC. Because the result of this
+ function is a closure, and hence topologically closed, the
+ resulting boundary can be represented using representational
+ geometry primitives as discussed in the OGC SPEC, section
+ 3.12.2.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>OGC SPEC s2.1.1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Buffer(geometry, double, [integer])</term>
+
+ <listitem>
+ <para>Returns a geometry that represents all points whose distance
+ from this Geometry is less than or equal to distance. Calculations
+ are in the Spatial Reference System of this Geometry. The optional
+ third parameter sets the number of segment used to approximate a
+ quarter circle (defaults to 8).</para>
+
+ <para>Performed by the GEOS module.</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_ConvexHull(geometry)</term>
+
+ <listitem>
+ <para>The convex hull of a geometry represents the minimum closed
+ geometry that encloses all geometries within the set.</para>
+
+ <para>It is usually used with MULTI and Geometry Collections.
+ Although it is not an aggregate - you can use it in conjunction
+ with ST_Collect to get the convex hull of a set of points.
+ ST_ConvexHull(ST_Collect(somepointfield)). It is often used to
+ determine an affected area based on a set of point
+ observations.</para>
+
+ <programlisting>SELECT d.disease_type, ST_ConvexHull(ST_Collect(d.the_geom)) As the_geom
+ FROM disease_obs As d
+ GROUP BY d.disease_type</programlisting>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Intersection(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set
+ intersection of the Geometries.</para>
+
+ <para>In other words - that portion of geometry A and geometry B
+ that is shared between the two geometries.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Shift_Longitude(geometry)</term>
+
+ <listitem>
+ <para>Reads every point/vertex in every component of every feature
+ in a geometry, and if the longitude coordinate is <0, adds 360
+ to it. The result would be a 0-360 version of the data to be
+ plotted in a 180 centric map</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SymDifference(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the portions of A and B
+ that do not intersect. It is called a symmetric difference because
+ ST_SymDifference(A,B) = ST_SymDifference(B,A).</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Difference(geometry A, geometry B)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents that part of geometry A
+ that does not intersect with geometry B.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Union(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set union of
+ the Geometries.</para>
+
+ <para>Performed by the GEOS module.</para>
+
+ <para>Do not call with a GeometryCollection as an argument.</para>
+
+ <para>NOTE: this function was formerly called GeomUnion(), which
+ was renamed from "Union" because UNION is an SQL reserved
+ word.</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Union(geometry set)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set union of
+ all Geometries in given set.</para>
+
+ <para>Performed by the GEOS module.</para>
+
+ <para>Do not call with a GeometryCollection in the argument
+ set.</para>
+
+ <para>Not explicitly defined in OGC SPEC.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MemUnion(geometry set)</term>
+
+ <listitem>
+ <para>Same as the above, only memory-friendly (uses less memory
+ and more processor time).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Accessors</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_AsText(geometry)</term>
+
+ <listitem>
+ <para>Return the Well-Known Text representation of the geometry.
+ For example: POLYGON(0 0,0 1,1 1,1 0,0 0)</para>
+
+ <para>OGC SPEC s2.1.1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsBinary(geometry)</term>
+
+ <listitem>
+ <para>Returns the geometry in the OGC "well-known-binary" format,
+ using the endian encoding of the server on which the database is
+ running. This is useful in binary cursors to pull data out of the
+ database without converting it to a string representation.</para>
+
+ <para>OGC SPEC s2.1.1.1 - also see
+ asBinary(<geometry>,'XDR') and
+ asBinary(<geometry>,'NDR')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SRID(geometry)</term>
+
+ <listitem>
+ <para>Returns the integer SRID number of the spatial reference
+ system of the geometry.</para>
+
+ <para>OGC SPEC s2.1.1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Dimension(geometry)</term>
+
+ <listitem>
+ <para>The inherent dimension of this Geometry object, which must
+ be less than or equal to the coordinate dimension. OGC SPEC
+ s2.1.1.1 - returns 0 for points, 1 for lines, 2 for polygons, and
+ the largest dimension of the components of a
+ GEOMETRYCOLLECTION.</para>
+
+ <programlisting>SELECT ST_dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0),POINT(0 0))');
+dimension
+-----------
+1</programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Envelope(geometry)</term>
+
+ <listitem>
+ <para>Returns a vald geometry (POINT, LINESTRING or POLYGON)
+ representing the bounding box of the geometry. Degenerate cases
+ (vertical lines, point) will return a geometry of lower dimension
+ than POLYGON.</para>
+
+ <para>OGC SPEC s2.1.1.1 - The minimum bounding box for this
+ Geometry, returned as a Geometry. The polygon is defined by the
+ corner points of the bounding box ((MINX, MINY), (MAXX, MINY),
+ (MAXX, MAXY), (MINX, MAXY), (MINX, MINY)).</para>
+
+ <para>NOTE:PostGIS will add a Zmin/Zmax coordinate as well.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsEmpty(geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is the empty geometry . If
+ true, then this Geometry represents the empty point set - i.e.
+ GEOMETRYCOLLECTION(EMPTY).</para>
+
+ <para>OGC SPEC s2.1.1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="IsSimple">
+ <term>ST_IsSimple(geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry has no anomalous geometric
+ points, such as self intersection or self tangency.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>OGC SPEC s2.1.1.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="IsClosed">
+ <term>ST_IsClosed(geometry)</term>
+
+ <listitem>
+ <para>Returns true of the geometry start and end points are
+ coincident.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsRing(geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Curve is closed (StartPoint ( ) =
+ EndPoint ( )) and this Curve is simple (does not pass through the
+ same point more than once).</para>
+
+ <para>performed by GEOS</para>
+
+ <para>OGC spec 2.1.5.1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumGeometries(geometry)</term>
+
+ <listitem>
+ <para>If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
+ number of geometries, otherwise return NULL.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeometryN(geometry,int)</term>
+
+ <listitem>
+ <para>Return the N'th geometry if the geometry is a
+ GEOMETRYCOLLECTION, MULTIPOINT, MULTILINESTRING or MULTIPOLYGON.
+ Otherwise, return NULL.</para>
+
+ <note>
+ <para>Index is 1-based as for OGC specs since version 0.8.0.
+ Previous versions implemented this as 0-based instead.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumPoints(geometry)</term>
+
+ <listitem>
+ <para>Find and return the number of points in the first linestring
+ in the geometry. Return NULL if there is no linestring in the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointN(geometry,integer)</term>
+
+ <listitem>
+ <para>Return the N'th point in the first linestring in the
+ geometry. Return NULL if there is no linestring in the
+ geometry.</para>
+
+ <note>
+ <para>Index is 1-based as for OGC specs since version 0.8.0.
+ Previous versions implemented this as 0-based instead.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_ExteriorRing(geometry)</term>
+
+ <listitem>
+ <para>Return the exterior ring of the polygon geometry. Return
+ NULL if the geometry is not a polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumInteriorRings(geometry)</term>
+
+ <listitem>
+ <para>Return the number of interior rings of the first polygon in
+ the geometry. Return NULL if there is no polygon in the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumInteriorRing(geometry)</term>
+
+ <listitem>
+ <para>Synonym to NumInteriorRings(geometry). The OpenGIS specs are
+ ambiguous about the exact function naming, so we provide both
+ spellings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_InteriorRingN(geometry,integer)</term>
+
+ <listitem>
+ <para>Return the N'th interior ring of the polygon geometry.
+ Return NULL if the geometry is not a polygon or the given N is out
+ of range.</para>
+
+ <note>
+ <para>Index is 1-based as for OGC specs since version 0.8.0.
+ Previous versions implemented this as 0-based instead.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_EndPoint(geometry)</term>
+
+ <listitem>
+ <para>Returns the last point of the LineString geometry as a
+ point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="StartPoint">
+ <term>ST_StartPoint(geometry)</term>
+
+ <listitem>
+ <para>Returns the first point of the LineString geometry as a
+ point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="GeometryType">
+ <term>GeometryType(geometry)</term>
+
+ <listitem>
+ <para>Returns the type of the geometry as a string. Eg:
+ 'LINESTRING', 'POLYGON', 'MULTIPOINT', etc.</para>
+
+ <para>OGC SPEC s2.1.1.1 - Returns the name of the instantiable
+ subtype of Geometry of which this Geometry instance is a member.
+ The name of the instantiable subtype of Geometry is returned as a
+ string.</para>
+
+ <note>
+ <para>This function also indicates if the geometry is measured,
+ by returning a string of the form 'POINTM'.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeometryType(geometry)</term>
+
+ <listitem>
+ <para>Returns the type of the geometry as a string. EG:
+ 'Linestring', 'Polygon', etc. This function differs from
+ GeometryType(geometry) in the case of the string that is returned,
+ as well as the fact that it will not indicate whether the geometry
+ is measured.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_X(geometry)</term>
+
+ <listitem>
+ <para>Return the X coordinate of the point. Input must be a
+ point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Y(geometry)</term>
+
+ <listitem>
+ <para>Return the Y coordinate of the point. Input must be a
+ point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Z(geometry)</term>
+
+ <listitem>
+ <para>Return the Z coordinate of the point, or NULL if not
+ available. Input must be a point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_M(geometry)</term>
+
+ <listitem>
+ <para>Return the M coordinate of the point, or NULL if not
+ available. Input must be a point.</para>
+
+ <note>
+ <para>This is not (yet) part of the OGC spec, but is listed here
+ to complete the point coordinate extractor function list.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Constructors</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_GeomFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a Point</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a Line</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LinestringFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>from the conformance suite</para>
+
+ <para>Throws an error if the WKT is not a Line</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolyFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a Polygon</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolygonFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>from the conformance suite</para>
+
+ <para>Throws an error if the WKT is not a Polygon</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPointFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a MULTIPOINT</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MLineFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a MULTILINESTRING</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPolyFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a MULTIPOLYGON</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomCollFromText(text,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKT with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>Throws an error if the WKT is not a
+ GEOMETRYCOLLECTION</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.6.2 - option SRID is from the conformance
+ suite</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeometryFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a POINT</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a LINESTRING</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LinestringFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>from the conformance suite</para>
+
+ <para>throws an error if WKB is not a LINESTRING</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolyFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a POLYGON</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolygonFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>from the conformance suite</para>
+
+ <para>throws an error if WKB is not a POLYGON</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPointFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a MULTIPOINT</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MLineFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a MULTILINESTRING</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPolyFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a MULTIPOLYGON</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomCollFromWKB(bytea,[<srid>])</term>
+
+ <listitem>
+ <para>Makes a Geometry from WKB with the given SRID. If SRID is
+ not give, it defaults to -1.</para>
+
+ <para>OGC SPEC 3.2.7.2 - option SRID is from the conformance
+ suite</para>
+
+ <para>throws an error if WKB is not a GEOMETRYCOLLECTION</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="BdPolyFromText">
+ <term>ST_BdPolyFromText(text WKT, integer SRID)</term>
+
+ <listitem>
+ <para>Construct a Polygon given an arbitrary collection of closed
+ linestrings as a MultiLineString text representation.</para>
+
+ <para>Throws an error if WKT is not a MULTILINESTRING. Throws an
+ error if output is a MULTIPOLYGON; use <link
+ linkend="BdMPolyFromText">BdMPolyFromText</link> in that case, or
+ see <link linkend="BuildArea">BuildArea()</link> for a
+ postgis-specific approach.</para>
+
+ <para>OGC SFSQL 1.1 - 3.2.6.2</para>
+
+ <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="BdMPolyFromText">
+ <term>ST_BdMPolyFromText(text WKT, integer SRID)</term>
+
+ <listitem>
+ <para>Construct a MultiPolygon given an arbitrary collection of
+ closed linestrings as a MultiLineString text
+ representation.</para>
+
+ <para>Throws an error if WKT is not a MULTILINESTRING. Forces
+ MULTIPOLYGON output even when result is really only composed by a
+ single POLYGON; use <link
+ linkend="BdPolyFromText">BdPolyFromText</link> if you're sure a
+ single POLYGON will result from operation, or see <link
+ linkend="BuildArea">BuildArea()</link> for a postgis-specific
+ approach.</para>
+
+ <para>OGC SFSQL 1.1 - 3.2.6.2</para>
+
+ <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>PostGIS Extensions</title>
+
+ <sect2>
+ <title>Management Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>DropGeometryTable([<schema_name>],
+ <table_name>)</term>
+
+ <listitem>
+ <para>Drops a table and all its references in geometry_columns.
+ Note: uses current_schema() on schema-aware pgsql installations if
+ schema is not provided.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>UpdateGeometrySRID([<schema_name>], <table_name>,
+ <column_name>, <srid>)</term>
+
+ <listitem>
+ <para>Update the SRID of all features in a geometry column
+ updating constraints and reference in geometry_columns. Note: uses
+ current_schema() on schema-aware pgsql installations if schema is
+ not provided.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>update_geometry_stats([<table_name>,
+ <column_name>])</term>
+
+ <listitem>
+ <para>Update statistics about spatial tables for use by the query
+ planner. You will also need to run "VACUUM ANALYZE [table_name]
+ [column_name]" for the statistics gathering process to be
+ complete. NOTE: starting with PostgreSQL 8.0 statistics gathering
+ is automatically performed running "VACUUM ANALYZE".</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_version()</term>
+
+ <listitem>
+ <para>Returns PostGIS version number and compile-time
+ options</para>
+
+ <note>
+ <para>Prior to version 1.1.0 this was a procedural function,
+ thus possibly returning inaccurate information (in case of
+ incomplete database upgrades).</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="postgis_lib_version">
+ <term>postgis_lib_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the PostGIS library.</para>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_lib_build_date()</term>
+
+ <listitem>
+ <para>Returns build date of the PostGIS library.</para>
+
+ <para>Availability: 1.0.0RC1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_script_build_date()</term>
+
+ <listitem>
+ <para>Returns build date of the PostGIS scripts.</para>
+
+ <para>Availability: 1.0.0RC1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_scripts_installed()</term>
+
+ <listitem>
+ <para>Returns version of the postgis scripts installed in this
+ database.</para>
+
+ <note>
+ <para>If the output of this function doesn't match the output of
+ <link
+ linkend="postgis_scripts_released">postgis_scripts_released()</link>
+ you probably missed to properly upgrade an existing database.
+ See the <link linkend="upgrading">Upgrading</link> section for
+ more info.</para>
+ </note>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="postgis_scripts_released">
+ <term>postgis_scripts_released()</term>
+
+ <listitem>
+ <para>Returns the version number of the lwpostgis.sql script
+ released with the installed postgis lib.</para>
+
+ <note>
+ <para>Starting with version 1.1.0 this function returns the same
+ value of <link
+ linkend="postgis_lib_version">postgis_lib_version()</link>. Kept
+ for backward compatibility.</para>
+ </note>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_geos_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the GEOS library, or NULL if
+ GEOS support is not enabled.</para>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_jts_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the JTS library, or NULL if
+ JTS support is not enabled.</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_proj_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the PROJ4 library, or NULL if
+ PROJ4 support is not enabled.</para>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_uses_stats()</term>
+
+ <listitem>
+ <para>Returns true if STATS usage has been enabled, false
+ otherwise.</para>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="postgis_full_version">
+ <term>postgis_full_version()</term>
+
+ <listitem>
+ <para>Reports full postgis version and build configuration
+ infos.</para>
+
+ <para>Availability: 0.9.0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Operators</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>A &< B</term>
+
+ <listitem>
+ <para>The "&<" operator returns true if A's bounding box
+ overlaps or is to the left of B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A &> B</term>
+
+ <listitem>
+ <para>The "&>" operator returns true if A's bounding box
+ overlaps or is to the right of B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A << B</term>
+
+ <listitem>
+ <para>The "<<" operator returns true if A's bounding box is
+ strictly to the left of B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A >> B</term>
+
+ <listitem>
+ <para>The ">>" operator returns true if A's bounding box is
+ strictly to the right of B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A &<| B</term>
+
+ <listitem>
+ <para>The "&<|" operator returns true if A's bounding box
+ overlaps or is below B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A |&> B</term>
+
+ <listitem>
+ <para>The "|&>" operator returns true if A's bounding box
+ overlaps or is above B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A <<| B</term>
+
+ <listitem>
+ <para>The "<<|" operator returns true if A's bounding box is
+ strictly below B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A |>> B</term>
+
+ <listitem>
+ <para>The "|>>" operator returns true if A's bounding box is
+ strictly above B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A ~= B</term>
+
+ <listitem>
+ <para>The "~=" operator is the "same as" operator. It tests actual
+ geometric equality of two features. So if A and B are the same
+ feature, vertex-by-vertex, the operator returns true.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A @ B</term>
+
+ <listitem>
+ <para>The "@" operator returns true if A's bounding box is
+ completely contained by B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A ~ B</term>
+
+ <listitem>
+ <para>The "~" operator returns true if A's bounding box completely
+ contains B's bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>A && B</term>
+
+ <listitem>
+ <para>The "&&" operator is the "overlaps" operator. If A's
+ bounding box overlaps B's bounding box the operator returns
+ true.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Measurement Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_area2d(geometry)</term>
+
+ <listitem>
+ <para>Returns the area of the geometry if it is a polygon or
+ multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_distance_sphere(point, point)</term>
+
+ <listitem>
+ <para>Returns linear distance in meters between two lat/lon
+ points. Uses a spherical earth and radius of 6370986 meters.
+ Faster than <link
+ linkend="distance_spheroid">distance_spheroid()</link>, but less
+ accurate. Only implemented for points.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="distance_spheroid">
+ <term>ST_distance_spheroid(point, point, spheroid)</term>
+
+ <listitem>
+ <para>Returns linear distance between two lat/lon points given a
+ particular spheroid. See the explanation of spheroids given for
+ <link linkend="length_spheroid">length_spheroid()</link>.
+ Currently only implemented for points.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="length2d">
+ <term>ST_length2d(geometry)</term>
+
+ <listitem>
+ <para>Returns the 2-dimensional length of the geometry if it is a
+ linestring or multi-linestring.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_length3d(geometry)</term>
+
+ <listitem>
+ <para>Returns the 3-dimensional length of the geometry if it is a
+ linestring or multi-linestring.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="length_spheroid">
+ <term>ST_length_spheroid(geometry,spheroid)</term>
+
+ <listitem>
+ <para>Calculates the length of of a geometry on an ellipsoid. This
+ is useful if the coordinates of the geometry are in
+ latitude/longitude and a length is desired without reprojection.
+ The ellipsoid is a separate database type and can be constructed
+ as follows:</para>
+
+ <literallayout>SPHEROID[<NAME>,<SEMI-MAJOR
+ AXIS>,<INVERSE FLATTENING>]</literallayout>
+
+ <para>Eg:</para>
+
+ <literallayout>SPHEROID["GRS_1980",6378137,298.257222101]</literallayout>
+
+ <para>An example calculation might look like this:</para>
+
+ <literallayout>SELECT length_spheroid( geometry_column,
+ 'SPHEROID["GRS_1980",6378137,298.257222101]' )
+ FROM geometry_table;</literallayout>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_length3d_spheroid(geometry,spheroid)</term>
+
+ <listitem>
+ <para>Calculates the length of of a geometry on an ellipsoid,
+ taking the elevation into account. This is just like
+ length_spheroid except vertical coordinates (expressed in the same
+ units as the spheroid axes) are used to calculate the extra
+ distance vertical displacement adds.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_distance(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns the smaller distance between two geometries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_max_distance(linestring,linestring)</term>
+
+ <listitem>
+ <para>Returns the largest distance between two line
+ strings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_perimeter(geometry)</term>
+
+ <listitem>
+ <para>Returns the 2-dimensional perimeter of the geometry, if it
+ is a polygon or multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_perimeter2d(geometry)</term>
+
+ <listitem>
+ <para>Returns the 2-dimensional perimeter of the geometry, if it
+ is a polygon or multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_perimeter3d(geometry)</term>
+
+ <listitem>
+ <para>Returns the 3-dimensional perimeter of the geometry, if it
+ is a polygon or multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_azimuth(geometry, geometry)</term>
+
+ <listitem>
+ <para>Returns the azimuth of the segment defined by the given
+ Point geometries, or NULL if the two points are coincident. Return
+ value is in radians.</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Outputs</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_AsBinary(geometry,{'NDR'|'XDR'})</term>
+
+ <listitem>
+ <para>Returns the geometry in the OGC "well-known-binary" format
+ as a bytea, using little-endian (NDR) or big-endian (XDR)
+ encoding. This is useful in binary cursors to pull data out of the
+ database without converting it to a string representation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsEWKT(geometry)</term>
+
+ <listitem>
+ <para>Returns a Geometry in EWKT format (as text).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsEWKB(geometry, {'NDR'|'XDR'})</term>
+
+ <listitem>
+ <para>Returns a Geometry in EWKB format (as bytea) using either
+ little-endian (NDR) or big-endian (XDR) encoding.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsHEXEWKB(geometry, {'NDR'|'XDR'})</term>
+
+ <listitem>
+ <para>Returns a Geometry in HEXEWKB format (as text) using either
+ little-endian (NDR) or big-endian (XDR) encoding.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsSVG(geometry, [rel], [precision])</term>
+
+ <listitem>
+ <para>Return the geometry as SVG path data. Use 1 as second
+ argument to have the path data implemented in terms of relative
+ moves, the default (or 0) uses absolute moves. Third argument may
+ be used to reduce the maximum number of decimal digits used in
+ output (defaults to 15). Point geometries will be rendered as
+ cx/cy when 'rel' arg is 0, x/y when 'rel' is 1. Multipoint
+ geometries are delimited by commas (","), GeometryCollection
+ geometries are delimited by semicolons (";").</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsGML([version], geometry, [precision])</term>
+
+ <listitem>
+ <para>Return the geometry as a GML element. The version parameter,
+ if specified, may be either 2 or 3. If no version parameter is
+ specified then the default is assumed to be 2. The third argument
+ may be used to reduce the maximum number of significant digits
+ used in output (defaults to 15).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsKML(geometry, [precision])</term>
+
+ <listitem>
+ <para>Return the geometry as a KML element. Second argument may be
+ used to reduce the maximum number of significant digits used in
+ output (defaults to 15).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsGeoJson([version], geometry, [precision],
+ [options])</term>
+
+ <listitem>
+ <para>Return the geometry as a GeoJson element. (Cf <ulink
+ url="http://wiki.geojson.org/GeoJSON_draft_version_6">GeoJson
+ specifications 1.0 RC6</ulink>). 2D and 3D Geometries are both
+ supported. GeoJson only support SFS 1.1 geometry type (no curve
+ support for example).</para>
+
+ <para>The version parameter, if specified, must be 1.</para>
+
+ <para>The third argument may be used to reduce the maximum number
+ of significant digits used in output (defaults to 15).</para>
+
+ <para>The last 'options' argument could be used to add Bbox or Crs
+ in GeoJSON output: <itemizedlist>
+ <listitem>
+ <para>0: means no option (default value)</para>
+ </listitem>
+
+ <listitem>
+ <para>1: GeoJson CRS</para>
+ </listitem>
+
+ <listitem>
+ <para>2: GeoJson Bbox</para>
+ </listitem>
+
+ <listitem>
+ <para>2: Both GeoJson Bbox and CRS</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Constructors</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_GeomFromEWKT(text)</term>
+
+ <listitem>
+ <para>Makes a Geometry from EWKT.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomFromEWKB(bytea)</term>
+
+ <listitem>
+ <para>Makes a Geometry from EWKB.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakePoint(<x>, <y>, [<z>],
+ [<m>])</term>
+
+ <listitem>
+ <para>Creates a 2d,3dz or 4d point geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakePointM(<x>, <y>, <m>)</term>
+
+ <listitem>
+ <para>Creates a 3dm point geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakeBox2D(<LL>, <UR>)</term>
+
+ <listitem>
+ <para>Creates a BOX2D defined by the given point
+ geometries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakeBox3D(<LLB>, <URT>)</term>
+
+ <listitem>
+ <para>Creates a BOX3D defined by the given point
+ geometries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakeLine(geometry set)</term>
+
+ <listitem>
+ <para>Creates a Linestring from a set of point geometries. You
+ might want to use a subselect to order points before feeding them
+ to this aggregate.</para>
+
+ <programlisting>
+SELECT gps.gps_track, ST_MakeLine(gps.the_geom) As newgeom
+ FROM (SELECT gps_track,gps_time, the_geom
+ FROM gps_points ORDER BY gps_track, gps_time) As gps
+ GROUP BY gps.gps_track
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakeLine(geometry, geometry)</term>
+
+ <listitem>
+ <para>Creates a Linestring from the two given point
+ geometries.</para>
+
+ <programlisting>
+SELECT ST_AsText(ST_MakeLine(ST_MakePoint(1,2), ST_MakePoint(3,4)))
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineFromMultiPoint(multipoint)</term>
+
+ <listitem>
+ <para>Creates a LineString from a MultiPoint geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakePolygon(linestring geometry)</term>
+
+ <listitem>
+ <para>Creates a Polygon formed by the given shell. Input
+ geometries must be closed LINESTRINGS (see <link
+ linkend="IsClosed">ST_IsClosed</link> and <link
+ linkend="GeometryType">ST_GeometryType</link>). This function will
+ not accept a MULTILINESTRING.</para>
+
+ <programlisting>
+SELECT ST_MakePolygon(ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5, 75.15 29.53)'));
+--If linestring is not closed
+--you can add the start point to close it
+SELECT ST_MakePolygon(ST_AddPoint(foo.open_line, ST_StartPoint(foo.open_line)))
+FROM (
+SELECT ST_GeomFromText('LINESTRING(75.15 29.53,77 29,77.6 29.5)') As open_line) As foo
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MakePolygon(linestring geometry, linestrings
+ geometry[])</term>
+
+ <listitem>
+ <para>Creates a Polygon formed by the given shell and array of
+ holes. You can construct a geometry array using <link
+ linkend="Accum">ST_Accum</link> or the PostgreSQL ARRAY[] and
+ ARRAY() constructs. Input geometries must be closed LINESTRINGS
+ (see <link linkend="IsClosed">ST_IsClosed</link> and <link
+ linkend="GeometryType">ST_GeometryType</link>).</para>
+
+ <programlisting>
+--Build a donut with an ant hole
+SELECT ST_MakePolygon(
+ ST_ExteriorRing(ST_Buffer(foo.line,10)),
+ ARRAY[ST_Translate(foo.line,1,1),
+ ST_ExteriorRing(ST_Buffer(ST_MakePoint(20,20),1)) ]
+ )
+FROM
+ (SELECT ST_ExteriorRing(ST_Buffer(ST_MakePoint(10,10),10,10))
+ As line )
+ As foo
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="BuildArea">
+ <term>ST_BuildArea(geometry)</term>
+
+ <listitem>
+ <para>Creates an areal geometry formed by the constituent linework
+ of given geometry. The return type can be a Polygon or
+ MultiPolygon, depending on input. If the input lineworks do not
+ form polygons NULL is returned.</para>
+
+ <para>See also <link
+ linkend="BdPolyFromText">BdPolyFromText</link> and <link
+ linkend="BdMPolyFromText">BdMPolyFromText</link> - wrappers to
+ this function with standard OGC interface.</para>
+
+ <para>Availability: 1.1.0 - requires GEOS >= 2.1.0.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Polygonize(geometry set)</term>
+
+ <listitem>
+ <para>Aggregate. Creates a GeometryCollection containing possible
+ polygons formed from the constituent linework of a set of
+ geometries.</para>
+
+ <para>Availability: 1.0.0RC1 - requires GEOS >= 2.1.0.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Collect(geometry set)</term>
+
+ <listitem>
+ <para>This function returns a GEOMETRYCOLLECTION or a MULTI object
+ from a set of geometries. The collect() function is an "aggregate"
+ function in the terminology of PostgreSQL. That means that it
+ operates on rows of data, in the same way the SUM() and AVG()
+ functions do. For example, "SELECT ST_Collect(GEOM) FROM GEOMTABLE
+ GROUP BY ATTRCOLUMN" will return a separate GEOMETRYCOLLECTION for
+ each distinct value of ATTRCOLUMN.</para>
+
+ <para>ST_Collect and ST_Union are often interchangeable.
+ ST_Collect is in general orders of magnitude faster than ST_Union
+ because it does not try to dissolve boundaries. It merely rolls up
+ single geometries into MULTI and MULTI or mixed geometry types
+ into Geometry Collections. Unfortunately geometry collections are
+ not well-supported by GIS tools. To prevent ST_Collect from
+ returning a Geometry Collection when collecting MULTI geometries,
+ one can use the below trick that utilizes ST_Dump to expand the
+ MULTIs out to singles and then regroup them.</para>
+
+ <programlisting>
+Thread ref: http://postgis.refractions.net/pipermail/postgis-users/2008-June/020331.html
+SELECT stusps,
+ ST_Multi(ST_Collect(f.the_geom)) as singlegeom
+ FROM (SELECT stusps, (ST_Dump(the_geom)).geom As the_geom
+ FROM
+ somestatetable ) As f
+GROUP BY stusps
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Collect(geometry, geometry)</term>
+
+ <listitem>
+ <para>This function returns a geometry being a collection of two
+ input geometries. Output type can be a MULTI* or a
+ GEOMETRYCOLLECTION.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Dump(geometry)</term>
+
+ <listitem>
+ <para>This is a set-returning function (SRF). It returns a set of
+ geometry_dump rows, formed by a geometry (geom) and an array of
+ integers (path). When the input geometry is a simple type
+ (POINT,LINESTRING,POLYGON) a single record will be returned with
+ an empty path array and the input geometry as geom. When the input
+ geometry is a collection or multi it will return a record for each
+ of the collection components, and the path will express the
+ position of the component inside the collection.</para>
+
+ <para>ST_Dump is useful for expanding geometries. It is the
+ reverse of a GROUP BY in that it creates new rows. For example it
+ can be use to expand MULTIPOLYGONS into POLYGONS.</para>
+
+ <programlisting>
+SELECT sometable.field1, sometable.field1,
+(ST_Dump(sometable.the_geom)).geom As the_geom
+ FROM sometable
+ </programlisting>
+
+ <para>Availability: PostGIS 1.0.0RC1. Requires PostgreSQL 7.3 or
+ higher.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_DumpRings(geometry)</term>
+
+ <listitem>
+ <para>This is a set-returning function (SRF). It returns a set of
+ geometry_dump rows, formed by a geometry (geom) and an array of
+ integers (path). The 'path' field holds the polygon ring index,
+ contains a single element: 0 for the shell, hole number for holes.
+ The 'geom' field contains the corresponding ring as a
+ polygon.</para>
+
+ <para>Availability: PostGIS 1.1.3. Requires PostgreSQL 7.3 or
+ higher.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Geometry Editors</title>
+
+ <variablelist>
+ <varlistentry id="addbbox">
+ <term>ST_AddBBOX(geometry)</term>
+
+ <listitem>
+ <para>Add bounding box to the geometry. This would make bounding
+ box based queries faster, but will increase the size of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="dropbbox">
+ <term>ST_DropBBOX(geometry)</term>
+
+ <listitem>
+ <para>Drop the bounding box cache from the geometry. This reduces
+ geometry size, but makes bounding-box based queries slower.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AddPoint(linestring geometry, point geometry)</term>
+
+ <term>ST_AddPoint(linestring geometry, point geometry, position
+ integer)</term>
+
+ <listitem>
+ <para>Adds a point to a LineString before point <position>
+ (0-based index). Third parameter can be omitted or set to -1 for
+ appending.</para>
+
+ <programlisting>
+--guarantee all linestrings in a table are closed
+--by adding the start point of each linestring to the end of the line string
+--only for those that are not closed
+UPDATE sometable
+ SET the_geom = ST_AddPoint(the_geom, ST_StartPoint(the_geom))
+ FROM sometable
+ WHERE ST_IsClosed(the_geom) = false;
+ </programlisting>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_RemovePoint(linestring, offset)</term>
+
+ <listitem>
+ <para>Removes point from a linestring. Offset is 0-based.</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SetPoint(linestring, N, point)</term>
+
+ <listitem>
+ <para>Replace point N of linestring with given point. Index is
+ 0-based.</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Force_collection(geometry)</term>
+
+ <listitem>
+ <para>Converts the geometry into a GEOMETRYCOLLECTION. This is
+ useful for simplifying the WKB representation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="force_2d">
+ <term>ST_Force_2d(geometry)</term>
+
+ <listitem>
+ <para>Forces the geometries into a "2-dimensional mode" so that
+ all output representations will only have the X and Y coordinates.
+ This is useful for force OGC-compliant output (since OGC only
+ specifies 2-D geometries).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="force_3dz">
+ <term>ST_Force_3dz(geometry)</term>
+
+ <term>ST_Force_3d(geometry)</term>
+
+ <listitem>
+ <para>Forces the geometries into XYZ mode.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="force_3dm">
+ <term>ST_Force_3dm(geometry)</term>
+
+ <listitem>
+ <para>Forces the geometries into XYM mode.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="force_4d">
+ <term>ST_Force_4d(geometry)</term>
+
+ <listitem>
+ <para>Forces the geometries into XYZM mode.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Multi(geometry)</term>
+
+ <listitem>
+ <para>Returns the geometry as a MULTI* geometry. If the geometry
+ is already a MULTI*, it is returned unchanged.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Transform(geometry,integer)</term>
+
+ <listitem>
+ <para>Returns a new geometry with its coordinates transformed to
+ the SRID referenced by the integer parameter. The destination SRID
+ must exist in the <varname>SPATIAL_REF_SYS</varname> table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Affine(geometry, float8, float8, float8, float8, float8,
+ float8, float8, float8, float8, float8, float8, float8)</term>
+
+ <listitem>
+ <para>Applies an 3d affine transformation to the geometry. The
+ call <programlisting>Affine(geom, a, b, c, d, e, f, g, h, i, xoff, yoff, zoff) </programlisting>
+ represents the transformation matrix <programlisting>/ a b c xoff \
+| d e f yoff |
+| g h i zoff |
+\ 0 0 0 1 /</programlisting> and the vertices are transformed as
+ follows: <programlisting>x' = a*x + b*y + c*z + xoff
+y' = d*x + e*y + f*z + yoff
+z' = g*x + h*y + i*z + zoff</programlisting> All of the translate / scale
+ functions below are expressed via such an affine
+ transformation.</para>
+
+ <para>Availability: 1.1.2.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Affine(geometry, float8, float8, float8, float8, float8,
+ float8)</term>
+
+ <listitem>
+ <para>Applies an 2d affine transformation to the geometry. The
+ call <programlisting>Affine(geom, a, b, d, e, xoff, yoff)</programlisting>
+ represents the transformation matrix <programlisting>/ a b 0 xoff \ / a b xoff \
+| d e 0 yoff | rsp. | d e yoff |
+| 0 0 1 0 | \ 0 0 1 /
+\ 0 0 0 1 /</programlisting> and the vertices are transformed as
+ follows: <programlisting>x' = a*x + b*y + xoff
+y' = d*x + e*y + yoff
+z' = z </programlisting> This method is a subcase of the 3D method
+ above.</para>
+
+ <para>Availability: 1.1.2.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Translate(geometry, float8, float8, float8)</term>
+
+ <listitem>
+ <para>Translates the geometry to a new location using the numeric
+ parameters as offsets. Ie: translate(geom, X, Y, Z).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Scale(geometry, float8, float8, float8)</term>
+
+ <listitem>
+ <para>scales the geometry to a new size by multiplying the
+ ordinates with the parameters. Ie: scale(geom, Xfactor, Yfactor,
+ Zfactor).</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="Rotate">
+ <term>ST_RotateZ(geometry, float8)</term>
+
+ <term>ST_RotateX(geometry, float8)</term>
+
+ <term>ST_RotateY(geometry, float8)</term>
+
+ <listitem>
+ <para>Rotate the geometry around the Z, X or Y axis by the given
+ angle given in radians. Follows the right-hand rule.</para>
+
+ <para>Availability: 1.1.2.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_TransScale(geometry, float8, float8, float8, float8)</term>
+
+ <listitem>
+ <para>First, translates the geometry using the first two floats,
+ then scales it using the second two floats, working in 2D only.
+ Using <code>transscale(geom, X, Y, XFactor, YFactor)</code>
+ internally calls <code>affine(geom, XFactor, 0, 0, 0, YFactor, 0,
+ 0, 0, 1, X*XFactor, Y*YFactor, 0)</code>.</para>
+
+ <para>Availability: 1.1.0.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Reverse(geometry)</term>
+
+ <listitem>
+ <para>Returns the geometry with vertex order reversed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_ForceRHR(geometry)</term>
+
+ <listitem>
+ <para>Force polygons of the collection to obey
+ Right-Hand-Rule.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Simplify(geometry, tolerance)</term>
+
+ <listitem>
+ <para>Returns a "simplified" version of the given geometry using
+ the Douglas-Peuker algorithm. Will actually do something only with
+ (multi)lines and (multi)polygons but you can safely call it with
+ any kind of geometry. Since simplification occurs on a
+ object-by-object basis you can also feed a GeometryCollection to
+ this function. Note that returned geometry might loose its
+ simplicity (see <link linkend="IsSimple">IsSimple</link>)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SimplifyPreserveTopology(geometry, tolerance)</term>
+
+ <listitem>
+ <para>Returns a "simplified" version of the given geometry using
+ the Douglas-Peuker algorithm. Will avoid creating derived
+ geometries (polygons in particular) that are invalid.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SnapToGrid(geometry, originX, originY, sizeX, sizeY)</term>
+
+ <term>ST_SnapToGrid(geometry, sizeX, sizeY)</term>
+
+ <term>ST_SnapToGrid(geometry, size)</term>
+
+ <listitem>
+ <para>Snap all points of the input geometry to the grid defined by
+ its origin and cell size. Remove consecutive points falling on the
+ same cell, eventually returning NULL if output points are not
+ enough to define a geometry of the given type. Collapsed
+ geometries in a collection are stripped from it.</para>
+
+ <note>
+ <para>The returned geometry might loose its simplicity (see
+ <link linkend="IsSimple">IsSimple</link>).</para>
+ </note>
+
+ <note>
+ <para>Before release 1.1.0 this function always returned a 2d
+ geometry. Starting at 1.1.0 the returned geometry will have same
+ dimensionality as the input one with higher dimension values
+ untouched. Use the version taking a second geometry argument to
+ define all grid dimensions.</para>
+ </note>
+
+ <para>Availability: 1.0.0RC1</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SnapToGrid(geometry, geometry, sizeX, sizeY, sizeZ,
+ sizeM)</term>
+
+ <listitem>
+ <para>Snap all points of the input geometry to the grid defined by
+ its origin (the second argument, must be a point) and cell sizes.
+ Specify 0 as size for any dimension you don't want to snap to a
+ grid.</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Segmentize(geometry, maxlength)</term>
+
+ <listitem>
+ <para>Return a modified geometry having no segment longer then the
+ given distance. Interpolated points will have Z and M values (if
+ needed) set to 0. Distance computation is performed in 2d
+ only.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineMerge(geometry)</term>
+
+ <listitem>
+ <para>Returns a (set of) LineString(s) formed by sewing together
+ constituent linework of input.</para>
+
+ <para>Availability: 1.1.0 - requires GEOS >= 2.1.0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Linear Referencing</title>
+
+ <variablelist>
+ <varlistentry id="line_interpolate_point">
+ <term>ST_line_interpolate_point(linestring, location)</term>
+
+ <listitem>
+ <para>Returns a point interpolated along a line. First argument
+ must be a LINESTRING. Second argument is a float8 between 0 and 1
+ representing fraction of total <link linkend="length2d">2d
+ length</link> the point has to be located.</para>
+
+ <para>See <link
+ linkend="line_locate_point">line_locate_point()</link> for
+ computing the line location nearest to a Point.</para>
+
+ <note>
+ <para>Since release 1.1.1 this function also interpolates M and
+ Z values (when present), while prior releases set them to
+ 0.0.</para>
+ </note>
+
+ <para>Availability: 0.8.2</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="line_substring">
+ <term>ST_line_substring(linestring, start, end)</term>
+
+ <listitem>
+ <para>Return a linestring being a substring of the input one
+ starting and ending at the given fractions of total 2d length.
+ Second and third arguments are float8 values between 0 and
+ 1.</para>
+
+ <para>If 'start' and 'end' have the same value this is equivalent
+ to <link
+ linkend="line_interpolate_point">line_interpolate_point()</link>.</para>
+
+ <para>See <link
+ linkend="line_locate_point">line_locate_point()</link> for
+ computing the line location nearest to a Point.</para>
+
+ <note>
+ <para>Since release 1.1.1 this function also interpolates M and
+ Z values (when present), while prior releases set them to
+ unspecified values.</para>
+ </note>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="line_locate_point">
+ <term>ST_line_locate_point(LineString, Point)</term>
+
+ <listitem>
+ <para>Returns a float between 0 and 1 representing the location of
+ the closest point on LineString to the given Point, as a fraction
+ of total <link linkend="length2d">2d line</link> length.</para>
+
+ <para>You can use the returned location to extract a Point (<link
+ linkend="line_interpolate_point">line_interpolate_point</link>) or
+ a substring (<link
+ linkend="line_substring">line_substring</link>).</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_locate_along_measure(geometry, float8)</term>
+
+ <listitem>
+ <para>Return a derived geometry collection value with elements
+ that match the specified measure. Polygonal elements are not
+ supported.</para>
+
+ <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text
+ for Continuation CD Editing Meeting</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_locate_between_measures(geometry, float8, float8)</term>
+
+ <listitem>
+ <para>Return a derived geometry collection value with elements
+ that match the specified range of measures inclusively. Polygonal
+ elements are not supported.</para>
+
+ <para>Semantic is specified by: ISO/IEC CD 13249-3:200x(E) - Text
+ for Continuation CD Editing Meeting</para>
+
+ <para>Availability: 1.1.0</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Misc</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_Summary(geometry)</term>
+
+ <listitem>
+ <para>Returns a text summary of the contents of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_box2d(geometry)</term>
+
+ <listitem>
+ <para>Returns a BOX2D representing the maximum extents of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_box3d(geometry)</term>
+
+ <listitem>
+ <para>Returns a BOX3D representing the maximum extents of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_extent(geometry set)</term>
+
+ <listitem>
+ <para>The extent() function is an "aggregate" function in the
+ terminology of PostgreSQL. That means that it operators on lists
+ of data, in the same way the sum() and mean() functions do. For
+ example, "SELECT ST_Extent(GEOM) FROM GEOMTABLE" will return a
+ BOX3D giving the maximum extent of all features in the table.
+ Similarly, "SELECT ST_Extent(GEOM) FROM GEOMTABLE GROUP BY
+ CATEGORY" will return one extent result for each category.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="zmflag">
+ <term>ST_zmflag(geometry)</term>
+
+ <listitem>
+ <para>Returns ZM (dimension semantic) flag of the geometries as a
+ small int. Values are: 0=2d, 1=3dm, 2=3dz, 3=4d.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="hasbbox">
+ <term>ST_HasBBOX(geometry)</term>
+
+ <listitem>
+ <para>Returns TRUE if the bbox of this geometry is cached, FALSE
+ otherwise. Use <link linkend="addbbox">addBBOX()</link> and <link
+ linkend="dropbbox">dropBBOX()</link> to control caching.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ndims">
+ <term>ST_ndims(geometry)</term>
+
+ <listitem>
+ <para>Returns number of dimensions of the geometry as a small int.
+ Values are: 2,3 or 4.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_nrings(geometry)</term>
+
+ <listitem>
+ <para>If the geometry is a polygon or multi-polygon returns the
+ number of rings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_npoints(geometry)</term>
+
+ <listitem>
+ <para>Returns the number of points in the geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="IsValid">
+ <term>ST_isvalid(geometry)</term>
+
+ <listitem>
+ <para>returns true if this geometry is valid.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_expand(geometry, float)</term>
+
+ <listitem>
+ <para>This function returns a bounding box expanded in all
+ directions from the bounding box of the input geometry, by an
+ amount specified in the second argument. Very useful for
+ distance() queries, to add an index filter to the query.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_estimated_extent([schema], table, geocolumn)</term>
+
+ <listitem>
+ <para>Return the 'estimated' extent of the given spatial table.
+ The estimated is taken from the geometry column's statistics. The
+ current schema will be used if not specified.</para>
+
+ <para>For PostgreSQL>=8.0.0 statistics are gathered by VACUUM
+ ANALYZE and resulting extent will be about 95% of the real
+ one.</para>
+
+ <para>For PostgreSQL<8.0.0 statistics are gathered by
+ update_geometry_stats() and resulting extent will be exact.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_find_srid(varchar,varchar,varchar)</term>
+
+ <listitem>
+ <para>The syntax is find_srid(<db/schema>, <table>,
+ <column>) and the function returns the integer SRID of the
+ specified column by searching through the GEOMETRY_COLUMNS table.
+ If the geometry column has not been properly added with the
+ AddGeometryColumns() function, this function will not work
+ either.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_mem_size(geometry)</term>
+
+ <listitem>
+ <para>Returns the amount of space (in bytes) the geometry
+ takes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_point_inside_circle(geometry, float, float, float)</term>
+
+ <listitem>
+ <para>The syntax for this functions is
+ point_inside_circle(<geometry>,<circle_center_x>,<circle_center_y>,<radius>).
+ Returns the true if the geometry is a point and is inside the
+ circle. Returns false otherwise.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_XMin(box3d) ST_YMin(box3d) ST_ZMin(box3d)</term>
+
+ <listitem>
+ <para>Returns the requested minima of a bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_XMax(box3d) ST_YMax(box3d) ST_ZMax(box3d)</term>
+
+ <listitem>
+ <para>Returns the requested maxima of a bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="Accum">
+ <term>ST_Accum(geometry set)</term>
+
+ <listitem>
+ <para>Aggregate. Constructs an array of geometries.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Long Transactions support</title>
+
+ <para>This module and associated pl/pgsql functions have been
+ implemented to provide long locking support required by <ulink
+ url="https://portal.opengeospatial.org/files/?artifact_id=7176">Web
+ Feature Service</ulink> specification.</para>
+
+ <note>
+ <para>Users must use <ulink
+ url="http://www.postgresql.org/docs/7.4/static/transaction-iso.html">serializable
+ transaction level</ulink> otherwise locking mechanism would
+ break.</para>
+ </note>
+
+ <variablelist>
+ <varlistentry id="EnableLongTransactions">
+ <term>EnableLongTransactions()</term>
+
+ <listitem>
+ <para>Enable long transaction support. This function creates the
+ required metadata tables, needs to be called once before using the
+ other functions in this section. Calling it twice is
+ harmless.</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="DisableLongTransactions">
+ <term>DisableLongTransactions()</term>
+
+ <listitem>
+ <para>Disable long transaction support. This function removes the
+ long transaction support metadata tables, and drops all triggers
+ attached to lock-checked tables.</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="CheckAuth">
+ <term>CheckAuth([<schema>], <table>,
+ <rowid_col>)</term>
+
+ <listitem>
+ <para>Check updates and deletes of rows in given table for being
+ authorized. Identify rows using <rowid_col> column.</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="LockRow">
+ <term>LockRow([<schema>], <table>, <rowid>,
+ <authid>, [<expires>])</term>
+
+ <listitem>
+ <para>Set lock/authorization for specific row in table
+ <authid> is a text value, <expires> is a timestamp
+ defaulting to now()+1hour. Returns 1 if lock has been assigned, 0
+ otherwise (already locked by other auth)</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="UnlockRows">
+ <term>UnlockRows(<authid>)</term>
+
+ <listitem>
+ <para>Remove all locks held by specified authorization id. Returns
+ the number of locks released.</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="AddAuth">
+ <term>AddAuth(<authid>)</term>
+
+ <listitem>
+ <para>Add an authorization token to be used in current
+ transaction.</para>
+
+ <para>Availability: 1.1.3</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>SQL-MM Functions</title>
+
+ <para>This is a listing of the SQL-MM defined functions that PostGIS
+ currently supports. The implementations of these functions follow the
+ ArcSDE implementation, and thus deviate somewhat from the spec. These
+ deviations will be noted.</para>
+
+ <para>As of version 1.2.0, these functions have been implemented by
+ wrapping existing PostGIS functions. As a result, full support for curved
+ geometries may not be in place for many functions.</para>
+
+ <note>
+ <para>SQL-MM defines the default SRID of all geometry constructors as 0.
+ PostGIS uses a default SRID of -1.</para>
+ </note>
+
+ <variablelist>
+ <varlistentry>
+ <term>ST_Area</term>
+
+ <listitem>
+ <para>Return the area measurement of an ST_Surface or
+ ST_MultiSurface value.</para>
+
+ <para>SQL-MM 3: 8.1.2, 9.5.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsBinary</term>
+
+ <listitem>
+ <para>Return the well-known binary representation of an ST_Geometry
+ value.</para>
+
+ <para>SQL-MM 3: 5.1.37</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_AsText</term>
+
+ <listitem>
+ <para>Return the well-known text representation of an ST_Geometry
+ value.</para>
+
+ <para>SQL-MM 3: 5.1.25</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Boundary</term>
+
+ <listitem>
+ <para>Return the boundary of the ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.14</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Buffer</term>
+
+ <listitem>
+ <para>Return a buffer around the ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.17</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Centroid</term>
+
+ <listitem>
+ <para>Return mathematical centroid of the ST_Surface or
+ ST_MultiSurface value.</para>
+
+ <para>SQL-MM 3: 8.1.4, 9.5.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Contains</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value spatially contains another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.31</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_ConvexHull</term>
+
+ <listitem>
+ <para>The convex hull of a geometry represents the minimum geometry
+ that encloses all geometries within the set.</para>
+
+ <para>It is usually used with MULTI and Geometry Collections.
+ Although it is not an aggregate - you can use it in conjunction with
+ ST_Collect to get the convex hull of a set of points.
+ ST_ConvexHull(ST_Collect(somepointfield)). It is often used to
+ determine an affected area based on a set of point
+ observations.</para>
+
+ <para>SQL-MM 3: 5.1.16</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_CoordDim</term>
+
+ <listitem>
+ <para>Return the coordinate dimension of the ST_Geometry
+ value.</para>
+
+ <para>SQL-MM 3: 5.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Crosses</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value spatially crosses another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.29</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Difference</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value that represents the point set
+ difference of two ST_Geometry values.</para>
+
+ <para>SQL-MM 3: 5.1.20</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Dimension</term>
+
+ <listitem>
+ <para>Return the dimension of the ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.2</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Disjoint</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value is spatially disjoint from
+ another ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.26</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Distance</term>
+
+ <listitem>
+ <para>Return the distance between two geometries.</para>
+
+ <para>SQL-MM 3: 5.1.23</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_EndPoint</term>
+
+ <listitem>
+ <para>Return an ST_Point value that is the end point of an ST_Curve
+ value.</para>
+
+ <para>SQL-MM 3: 7.1.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Envelope</term>
+
+ <listitem>
+ <para>Return the bounding rectangle for the ST_Geometry
+ value.</para>
+
+ <para>SQL-MM 3: 5.1.15</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Equals</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value as spatially equal to another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.24</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_ExteriorRing</term>
+
+ <listitem>
+ <para>Return the exterior ring of an ST_Surface</para>
+
+ <para>SQL-MM 3: 8.2.3, 8.3.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeometryN</term>
+
+ <listitem>
+ <para>Return the indicated ST_Geometry value from an
+ ST_GeomCollection.</para>
+
+ <para>SQL-MM 3: 9.1.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeometryType</term>
+
+ <listitem>
+ <para>Return the geometry type of the ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.40</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_GeomFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.41</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_InteriorRingN</term>
+
+ <listitem>
+ <para>Return the specified interior ring of an ST_Surface
+ value.</para>
+
+ <para>SQL-MM 3: 8.2.6, 8.3.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Intersection</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value that represents the point set
+ intersection of two ST_Geometry values.</para>
+
+ <para>In other words - that portion of geometry A and geometry B
+ that is shared between the two geometries.</para>
+
+ <para>SQL-MM 3: 5.1.18</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Intersects</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value spatially intersects another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.27</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsClosed</term>
+
+ <listitem>
+ <para>Test if an ST_Curve or ST_MultiCurve value is closed.</para>
+
+ <note>
+ <para>SQL-MM defines the result of ST_IsClosed(NULL) to be 0,
+ while PostGIS returns NULL.</para>
+ </note>
+
+ <para>SQL-MM 3: 7.1.5, 9.3.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsEmpty</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value corresponds to the empty
+ set.</para>
+
+ <note>
+ <para>SQL-MM defines the result of ST_IsEmpty(NULL) to be 0, while
+ PostGIS returns NULL.</para>
+ </note>
+
+ <para>SQL-MM 3: 5.1.7</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsRing</term>
+
+ <listitem>
+ <para>Test if an ST_Curve value is a ring.</para>
+
+ <note>
+ <para>SQL-MM defines the result of ST_IsRing(NULL) to be 0, while
+ PostGIS returns NULL.</para>
+ </note>
+
+ <para>SQL-MM 3: 7.1.6</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsSimple</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value has no anomalous geometric
+ points, such as self intersection or self tangency.</para>
+
+ <note>
+ <para>SQL-MM defines the result of ST_IsSimple(NULL) to be 0,
+ while PostGIS returns NULL.</para>
+ </note>
+
+ <para>SQL-MM 3: 5.1.8</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_IsValid</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value is well formed.</para>
+
+ <note>
+ <para>SQL-MM defines the result of ST_IsValid(NULL) to be 0, while
+ PostGIS returns NULL.</para>
+ </note>
+
+ <para>SQL-MM defines the result of ST_IsValid(NULL) to be 1</para>
+
+ <para>SQL-MM 3: 5.1.9</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Length</term>
+
+ <listitem>
+ <para>Return the length measurement of an ST_Curve or ST_MultiCurve
+ value.</para>
+
+ <para>SQL-MM 3: 7.1.2, 9.3.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_LineString value.</para>
+
+ <para>SQL-MM 3: 7.2.8</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_LineFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_LineString value.</para>
+
+ <para>SQL-MM 3: 7.2.9</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MLineFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiLineString value.</para>
+
+ <para>SQL-MM 3: 9.4.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MLineFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiLineString value.</para>
+
+ <para>SQL-MM 3: 9.4.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPointFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiPoint value.</para>
+
+ <para>SQL-MM 3: 9.2.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPointFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiPoint value.</para>
+
+ <para>SQL-MM 3: 9.2.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPolyFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiPolygon value.</para>
+
+ <para>SQL-MM 3: 9.6.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_MPolyFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_MultiPolygon value.</para>
+
+ <para>SQL-MM 3: 9.6.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumGeometries</term>
+
+ <listitem>
+ <para>Return the number of geometries in an
+ ST_GeomCollection.</para>
+
+ <para>SQL-MM 3: 9.1.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumInteriorRing</term>
+
+ <listitem>
+ <para>Return the number of interior rings in an ST_Surface.</para>
+
+ <para>SQL-MM 3: 8.2.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_NumPoints</term>
+
+ <listitem>
+ <para>Return the number of points in an ST_LineString or
+ ST_CircularString value.</para>
+
+ <para>SQL-MM 3: 7.2.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_OrderingEquals</term>
+
+ <listitem>
+ <para>ST_OrderingEquals compares two geometries and t (TRUE) if the
+ geometries are equal and the coordinates are in the same order;
+ otherwise it returns f (FALSE).</para>
+
+ <note>
+ <para>This function is implemented as per the ArcSDE SQL
+ specification rather than SQL-MM.
+ http://edndoc.esri.com/arcsde/9.1/sql_api/sqlapi3.htm#ST_OrderingEquals</para>
+ </note>
+
+ <para>SQL-MM 3: 5.1.43</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Overlaps</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value spatially overlays another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.32</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Perimeter</term>
+
+ <listitem>
+ <para>Return the length measurement of the boundary of an ST_Surface
+ or ST_MultiRSurface value.</para>
+
+ <para>SQL-MM 3: 8.1.3, 9.5.4</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Point</term>
+
+ <listitem>
+ <para>Returns an ST_Point with the given coordinate values.</para>
+
+ <para>SQL-MM 3: 6.1.2</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_Point value.</para>
+
+ <para>SQL-MM 3: 6.1.8</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_Point value.</para>
+
+ <para>SQL-MM 3: 6.1.9</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointN</term>
+
+ <listitem>
+ <para>Return the specified ST_Point value in an ST_LineString or
+ ST_CircularString</para>
+
+ <para>SQL-MM 3: 7.2.5, 7.3.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PointOnSurface</term>
+
+ <listitem>
+ <para>Return an ST_Point value guaranteed to spatially intersect the
+ ST_Surface or ST_MultiSurface value.</para>
+
+ <para>SQL-MM 3: 8.1.5, 9.5.6</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolyFromText</term>
+
+ <listitem>
+ <para>Return a specified ST_Polygon value.</para>
+
+ <para>SQL-MM 3: 8.3.6</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_PolyFromWKB</term>
+
+ <listitem>
+ <para>Return a specified ST_Polygon value.</para>
+
+ <para>SQL-MM 3: 8.3.7</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Polygon</term>
+
+ <listitem>
+ <para>Return a polygon build from the specified linestring and
+ SRID.</para>
+
+ <para>SQL-MM 3: 8.3.2</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Relate</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value is spatially related to another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.25</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SRID</term>
+
+ <listitem>
+ <para>Return the spatial reference system identifier of the
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.5</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_StartPoint</term>
+
+ <listitem>
+ <para>Return an ST_Point value that is the start point of an
+ ST_Curve value.</para>
+
+ <para>SQL-MM 3: 7.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_SymDifference</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value that represents the point set
+ symmetric difference of two ST_Geometry values.</para>
+
+ <para>SQL-MM 3: 5.1.21</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Touches</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value spatially touches another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.28</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Transform</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value transformed to the specified
+ spatial reference system.</para>
+
+ <para>SQL-MM 3: 5.1.6</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Union</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value that represents the point set
+ union of two ST_Geometry values.</para>
+
+ <para>SQL-MM 3: 5.1.19</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Within</term>
+
+ <listitem>
+ <para>Test if an ST_Geometry value is spatially within another
+ ST_Geometry value.</para>
+
+ <para>SQL-MM 3: 5.1.30</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_WKBToSQL</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value for a given well-known binary
+ representation.</para>
+
+ <para>SQL-MM 3: 5.1.36</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_WKTToSQL</term>
+
+ <listitem>
+ <para>Return an ST_Geometry value for a given well-known text
+ representation.</para>
+
+ <para>SQL-MM 3: 5.1.34</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_X</term>
+
+ <listitem>
+ <para>Returns the x coordinate value of an ST_Point value.</para>
+
+ <para>SQL-MM 3: 6.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ST_Y</term>
+
+ <listitem>
+ <para>Returns the y coordinate value of an ST_Point value.</para>
+
+ <para>SQL-MM 3: 6.1.4</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>ArcSDE Functions</title>
+
+ <para>Additional functions have been added to improve support for an
+ ArcSDE style interface.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SE_EnvelopesIntersect</term>
+
+ <listitem>
+ <para>Returns t (TRUE) if the envelopes of two geometries intersect;
+ otherwise, it returns f (FALSE).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_Is3d</term>
+
+ <listitem>
+ <para>Test if a geometry value has z coordinate values.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_IsMeasured</term>
+
+ <listitem>
+ <para>Test if a geometry value has m coordinate values.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_LocateAlong</term>
+
+ <listitem>
+ <para>Return a derived geometry collection value with elements that
+ match the specified measur.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_LocateBetween</term>
+
+ <listitem>
+ <para>Return a derived geometry collection value with elements that
+ match the specified range of measures inclusively.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_M</term>
+
+ <listitem>
+ <para>Returns the m coordinate value of an ST_Point value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SE_Z</term>
+
+ <listitem>
+ <para>Returns the z coordinate value of an ST_Point value</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+</chapter>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix id="release_notes">
+ <title>Appendix</title>
+
+ <sect1>
+ <title>Release Notes</title>
+
+ <sect2>
+ <title>Release 1.3.3</title>
+
+ <para>Release date: 2008/04/12</para>
+
+ <para>This release fixes bugs shp2pgsql, adds enhancements to SVG and
+ KML support, adds a ST_SimplifyPreserveTopology function, makes the
+ build more sensitive to GEOS versions, and fixes a handful of severe but
+ rare failure cases.</para>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.3.2</title>
+
+ <para>Release date: 2007/12/01</para>
+
+ <para>This release fixes bugs in ST_EndPoint() and ST_Envelope, improves
+ support for JDBC building and OS/X, and adds better support for GML
+ output with ST_AsGML(), including GML3 output.</para>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.3.1</title>
+
+ <para>Release date: 2007/08/13</para>
+
+ <para>This release fixes some oversights in the previous release around
+ version numbering, documentation, and tagging.</para>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.3.0</title>
+
+ <para>Release date: 2007/08/09</para>
+
+ <para>This release provides performance enhancements to the relational
+ functions, adds new relational functions and begins the migration of our
+ function names to the SQL-MM convension, using the spatial type (SP)
+ prefix.</para>
+
+ <sect3>
+ <title>Added Functionality</title>
+
+ <para>JDBC: Added Hibernate Dialect (thanks to Norman Barker)</para>
+
+ <para>Added ST_Covers and ST_CoveredBy relational functions.
+ Description and justification of these functions can be found at
+ http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html</para>
+
+ <para>Added ST_DWithin relational function.</para>
+ </sect3>
+
+ <sect3>
+ <title>Performance Enhancements</title>
+
+ <para>Added cached and indexed point-in-polygon short-circuits for the
+ functions ST_Contains, ST_Intersects, ST_Within and ST_Disjoint</para>
+
+ <para>Added inline index support for relational functions (except
+ ST_Disjoint)</para>
+ </sect3>
+
+ <sect3>
+ <title>Other Changes</title>
+
+ <para>Extended curved geometry support into the geometry accessor and
+ some processing functions</para>
+
+ <para>Began migration of functions to the SQL-MM naming convension;
+ using a spatial type (ST) prefix.</para>
+
+ <para>Added initial support for PostgreSQL 8.3</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.2.1</title>
+
+ <para>Release date: 2007/01/11</para>
+
+ <para>This release provides bug fixes in PostgreSQL 8.2 support and some
+ small performance enhancements.</para>
+
+ <sect3>
+ <title>Changes</title>
+
+ <para>Fixed point-in-polygon shortcut bug in Within().</para>
+
+ <para>Fixed PostgreSQL 8.2 NULL handling for indexes.</para>
+
+ <para>Updated RPM spec files.</para>
+
+ <para>Added short-circuit for Transform() in no-op case.</para>
+
+ <para>JDBC: Fixed JTS handling for multi-dimensional geometries
+ (thanks to Thomas Marti for hint and partial patch). Additionally, now
+ JavaDoc is compiled and packaged. Fixed classpath problems with GCJ.
+ Fixed pgjdbc 8.2 compatibility, losing support for jdk 1.3 and
+ older.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.2.0</title>
+
+ <para>Release date: 2006/12/08</para>
+
+ <para>This release provides type definitions along with
+ serialization/deserialization capabilities for SQL-MM defined curved
+ geometries, as well as performance enhancements.</para>
+
+ <sect3>
+ <title>Changes</title>
+
+ <para>Added curved geometry type support for
+ serialization/deserialization</para>
+
+ <para>Added point-in-polygon shortcircuit to the Contains and Within
+ functions to improve performance for these cases.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.6</title>
+
+ <para>Release date: 2006/11/02</para>
+
+ <para>This is a bugfix release, in particular fixing a critical error
+ with GEOS interface in 64bit systems. Includes an updated of the SRS
+ parameters and an improvement in reprojections (take Z in
+ consideration). Upgrade is <emphasis>encouraged</emphasis>.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>fixed CAPI change that broke 64-bit platforms</para>
+
+ <para>loader/dumper: fixed regression tests and usage output</para>
+
+ <para>Fixed setSRID() bug in JDBC, thanks to Thomas Marti</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>use Z ordinate in reprojections</para>
+
+ <para>spatial_ref_sys.sql updated to EPSG 6.11.1</para>
+
+ <para>Simplified Version.config infrastructure to use a single pack of
+ version variables for everything.</para>
+
+ <para>Include the Version.config in loader/dumper USAGE
+ messages</para>
+
+ <para>Replace hand-made, fragile JDBC version parser with
+ Properties</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.5</title>
+
+ <para>Release date: 2006/10/13</para>
+
+ <para>This is an bugfix release, including a critical segfault on win32.
+ Upgrade is <emphasis>encouraged</emphasis>.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fixed MingW link error that was causing pgsql2shp to segfault on
+ Win32 when compiled for PostgreSQL 8.2</para>
+
+ <para>fixed nullpointer Exception in Geometry.equals() method in
+ Java</para>
+
+ <para>Added EJB3Spatial.odt to fulfill the GPL requirement of
+ distributing the "preferred form of modification"</para>
+
+ <para>Removed obsolete synchronization from JDBC Jts code.</para>
+
+ <para>Updated heavily outdated README files for shp2pgsql/pgsql2shp by
+ merging them with the manpages.</para>
+
+ <para>Fixed version tag in jdbc code that still said "1.1.3" in the
+ "1.1.4" release.</para>
+ </sect3>
+
+ <sect3>
+ <title>New Features</title>
+
+ <para>Added -S option for non-multi geometries to shp2pgsql</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.4</title>
+
+ <para>Release date: 2006/09/27</para>
+
+ <para>This is an bugfix release including some improvements in the Java
+ interface. Upgrade is <emphasis>encouraged</emphasis>.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fixed support for PostgreSQL 8.2</para>
+
+ <para>Fixed bug in collect() function discarding SRID of input</para>
+
+ <para>Added SRID match check in MakeBox2d and MakeBox3d</para>
+
+ <para>Fixed regress tests to pass with GEOS-3.0.0</para>
+
+ <para>Improved pgsql2shp run concurrency.</para>
+ </sect3>
+
+ <sect3>
+ <title>Java changes</title>
+
+ <para>reworked JTS support to reflect new upstream JTS developers'
+ attitude to SRID handling. Simplifies code and drops build depend on
+ GNU trove.</para>
+
+ <para>Added EJB2 support generously donated by the "Geodetix s.r.l.
+ Company" http://www.geodetix.it/</para>
+
+ <para>Added EJB3 tutorial / examples donated by Norman Barker
+ <nbarker@ittvis.com></para>
+
+ <para>Reorganized java directory layout a little.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.3</title>
+
+ <para>Release date: 2006/06/30</para>
+
+ <para>This is an bugfix release including also some new functionalities
+ (most notably long transaction support) and portability enhancements.
+ Upgrade is <emphasis>encouraged</emphasis>.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes / correctness</title>
+
+ <para>BUGFIX in distance(poly,poly) giving wrong results.</para>
+
+ <para>BUGFIX in pgsql2shp successful return code.</para>
+
+ <para>BUGFIX in shp2pgsql handling of MultiLine WKT.</para>
+
+ <para>BUGFIX in affine() failing to update bounding box.</para>
+
+ <para>WKT parser: forbidden construction of multigeometries with EMPTY
+ elements (still supported for GEOMETRYCOLLECTION).</para>
+ </sect3>
+
+ <sect3>
+ <title>New functionalities</title>
+
+ <para>NEW Long Transactions support.</para>
+
+ <para>NEW DumpRings() function.</para>
+
+ <para>NEW AsHEXEWKB(geom, XDR|NDR) function.</para>
+ </sect3>
+
+ <sect3>
+ <title>JDBC changes</title>
+
+ <para>Improved regression tests: MultiPoint and scientific
+ ordinates</para>
+
+ <para>Fixed some minor bugs in jdbc code</para>
+
+ <para>Added proper accessor functions for all fields in preparation of
+ making those fields private later</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>NEW regress test support for loader/dumper.</para>
+
+ <para>Added --with-proj-libdir and --with-geos-libdir configure
+ switches.</para>
+
+ <para>Support for build Tru64 build.</para>
+
+ <para>Use Jade for generating documentation.</para>
+
+ <para>Don't link pgsql2shp to more libs then required.</para>
+
+ <para>Initial support for PostgreSQL 8.2.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.2</title>
+
+ <para>Release date: 2006/03/30</para>
+
+ <para>This is an bugfix release including some new functions and
+ portability enhancements. Upgrade is
+ <emphasis>encouraged</emphasis>.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>BUGFIX in SnapToGrid() computation of output bounding box</para>
+
+ <para>BUGFIX in EnforceRHR()</para>
+
+ <para>jdbc2 SRID handling fixes in JTS code</para>
+
+ <para>Fixed support for 64bit archs</para>
+ </sect3>
+
+ <sect3>
+ <title>New functionalities</title>
+
+ <para>Regress tests can now be run *before* postgis
+ installation</para>
+
+ <para>New affine() matrix transformation functions</para>
+
+ <para>New rotate{,X,Y,Z}() function</para>
+
+ <para>Old translating and scaling functions now use affine()
+ internally</para>
+
+ <para>Embedded access control in estimated_extent() for builds against
+ pgsql >= 8.0.0</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>More portable ./configure script</para>
+
+ <para>Changed ./run_test script to have more sane default
+ behaviour</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.1</title>
+
+ <para>Release date: 2006/01/23</para>
+
+ <para>This is an important Bugfix release, upgrade is <emphasis>highly
+ recommended</emphasis>. Previous version contained a bug in
+ postgis_restore.pl preventing <link linkend="hard_upgrade">hard
+ upgrade</link> procedure to complete and a bug in GEOS-2.2+ connector
+ preventing GeometryCollection objects to be used in topological
+ operations.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later follow the
+ <link linkend="soft_upgrade">soft upgrade</link> procedure.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fixed a premature exit in postgis_restore.pl</para>
+
+ <para>BUGFIX in geometrycollection handling of GEOS-CAPI
+ connector</para>
+
+ <para>Solaris 2.7 and MingW support improvements</para>
+
+ <para>BUGFIX in line_locate_point()</para>
+
+ <para>Fixed handling of postgresql paths</para>
+
+ <para>BUGFIX in line_substring()</para>
+
+ <para>Added support for localized cluster in regress tester</para>
+ </sect3>
+
+ <sect3>
+ <title>New functionalities</title>
+
+ <para>New Z and M interpolation in line_substring()</para>
+
+ <para>New Z and M interpolation in line_interpolate_point()</para>
+
+ <para>added NumInteriorRing() alias due to OpenGIS ambiguity</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.1.0</title>
+
+ <para>Release date: 2005/12/21</para>
+
+ <para>This is a Minor release, containing many improvements and new
+ things. Most notably: build procedure greatly simplified; transform()
+ performance drastically improved; more stable GEOS connectivity (CAPI
+ support); lots of new functions; draft topology support.</para>
+
+ <para>It is <emphasis>highly recommended</emphasis> that you upgrade to
+ GEOS-2.2.x before installing PostGIS, this will ensure future GEOS
+ upgrades won't require a rebuild of the PostGIS library.</para>
+
+ <sect3>
+ <title>Credits</title>
+
+ <para>This release includes code from Mark Cave Ayland for caching of
+ proj4 objects. Markus Schaber added many improvements in his JDBC2
+ code. Alex Bodnaru helped with PostgreSQL source dependency relief and
+ provided Debian specfiles. Michael Fuhr tested new things on Solaris
+ arch. David Techer and Gerald Fenoy helped testing GEOS C-API
+ connector. Hartmut Tschauner provided code for the azimuth() function.
+ Devrim GUNDUZ provided RPM specfiles. Carl Anderson helped with the
+ new area building functions. See the <link
+ linkend="credits">credits</link> section for more names.</para>
+ </sect3>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later you
+ <emphasis>DO NOT</emphasis> need a dump/reload. Simply sourcing the
+ new lwpostgis_upgrade.sql script in all your existing databases will
+ work. See the <link linkend="soft_upgrade">soft upgrade</link> chapter
+ for more information.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>New functions</title>
+
+ <para>scale() and transscale() companion methods to translate()</para>
+
+ <para>line_substring()</para>
+
+ <para>line_locate_point()</para>
+
+ <para>M(point)</para>
+
+ <para>LineMerge(geometry)</para>
+
+ <para>shift_longitude(geometry)</para>
+
+ <para>azimuth(geometry)</para>
+
+ <para>locate_along_measure(geometry, float8)</para>
+
+ <para>locate_between_measures(geometry, float8, float8)</para>
+
+ <para>SnapToGrid by point offset (up to 4d support)</para>
+
+ <para>BuildArea(any_geometry)</para>
+
+ <para>OGC BdPolyFromText(linestring_wkt, srid)</para>
+
+ <para>OGC BdMPolyFromText(linestring_wkt, srid)</para>
+
+ <para>RemovePoint(linestring, offset)</para>
+
+ <para>ReplacePoint(linestring, offset, point)</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fixed memory leak in polygonize()</para>
+
+ <para>Fixed bug in lwgeom_as_anytype cast functions</para>
+
+ <para>Fixed USE_GEOS, USE_PROJ and USE_STATS elements of
+ postgis_version() output to always reflect library state.</para>
+ </sect3>
+
+ <sect3>
+ <title>Function semantic changes</title>
+
+ <para>SnapToGrid doesn't discard higher dimensions</para>
+
+ <para>Changed Z() function to return NULL if requested dimension is
+ not available</para>
+ </sect3>
+
+ <sect3>
+ <title>Performance improvements</title>
+
+ <para>Much faster transform() function, caching proj4 objects</para>
+
+ <para>Removed automatic call to fix_geometry_columns() in
+ AddGeometryColumns() and update_geometry_stats()</para>
+ </sect3>
+
+ <sect3>
+ <title>JDBC2 works</title>
+
+ <para>Makefile improvements</para>
+
+ <para>JTS support improvements</para>
+
+ <para>Improved regression test system</para>
+
+ <para>Basic consistency check method for geometry collections</para>
+
+ <para>Support for (Hex)(E)wkb</para>
+
+ <para>Autoprobing DriverWrapper for HexWKB / EWKT switching</para>
+
+ <para>fix compile problems in ValueSetter for ancient jdk
+ releases.</para>
+
+ <para>fix EWKT constructors to accept SRID=4711; representation</para>
+
+ <para>added preliminary read-only support for java2d geometries</para>
+ </sect3>
+
+ <sect3>
+ <title>Other new things</title>
+
+ <para>Full autoconf-based configuration, with PostgreSQL source
+ dependency relief</para>
+
+ <para>GEOS C-API support (2.2.0 and higher)</para>
+
+ <para>Initial support for topology modelling</para>
+
+ <para>Debian and RPM specfiles</para>
+
+ <para>New lwpostgis_upgrade.sql script</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>JTS support improvements</para>
+
+ <para>Stricter mapping between DBF and SQL integer and string
+ attributes</para>
+
+ <para>Wider and cleaner regression test suite</para>
+
+ <para>old jdbc code removed from release</para>
+
+ <para>obsoleted direct use of postgis_proc_upgrade.pl</para>
+
+ <para>scripts version unified with release version</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.6</title>
+
+ <para>Release date: 2005/12/06</para>
+
+ <para>Contains a few bug fixes and improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later you
+ <emphasis>DO NOT</emphasis> need a dump/reload.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fixed palloc(0) call in collection deserializer (only gives
+ problem with --enable-cassert)</para>
+
+ <para>Fixed bbox cache handling bugs</para>
+
+ <para>Fixed geom_accum(NULL, NULL) segfault</para>
+
+ <para>Fixed segfault in addPoint()</para>
+
+ <para>Fixed short-allocation in lwcollection_clone()</para>
+
+ <para>Fixed bug in segmentize()</para>
+
+ <para>Fixed bbox computation of SnapToGrid output</para>
+ </sect3>
+
+ <sect3>
+ <title>Improvements</title>
+
+ <para>Initial support for postgresql 8.2</para>
+
+ <para>Added missing SRID mismatch checks in GEOS ops</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.5</title>
+
+ <para>Release date: 2005/11/25</para>
+
+ <para>Contains memory-alignment fixes in the library, a segfault fix in
+ loader's handling of UTF8 attributes and a few improvements and
+ cleanups.</para>
+
+ <note>
+ <para>Return code of shp2pgsql changed from previous releases to
+ conform to unix standards (return 0 on success).</para>
+ </note>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 or later you
+ <emphasis>DO NOT</emphasis> need a dump/reload.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>Fixed memory alignment problems</para>
+
+ <para>Fixed computation of null values fraction in analyzer</para>
+
+ <para>Fixed a small bug in the getPoint4d_p() low-level
+ function</para>
+
+ <para>Speedup of serializer functions</para>
+
+ <para>Fixed a bug in force_3dm(), force_3dz() and force_4d()</para>
+ </sect3>
+
+ <sect3>
+ <title>Loader changes</title>
+
+ <para>Fixed return code of shp2pgsql</para>
+
+ <para>Fixed back-compatibility issue in loader (load of null
+ shapefiles)</para>
+
+ <para>Fixed handling of trailing dots in dbf numerical
+ attributes</para>
+
+ <para>Segfault fix in shp2pgsql (utf8 encoding)</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>Schema aware postgis_proc_upgrade.pl, support for pgsql
+ 7.2+</para>
+
+ <para>New "Reporting Bugs" chapter in manual</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.4</title>
+
+ <para>Release date: 2005/09/09</para>
+
+ <para>Contains important bug fixes and a few improvements. In
+ particular, it fixes a memory leak preventing successful build of GiST
+ indexes for large spatial tables.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.3 you <emphasis>DO
+ NOT</emphasis> need a dump/reload.</para>
+
+ <para>If you are upgrading from a release <emphasis>between 1.0.0RC6
+ and 1.0.2</emphasis> (inclusive) and really want a live upgrade read
+ the <link linkend="rel_1.0.3_upgrading">upgrade section</link> of the
+ 1.0.3 release notes chapter.</para>
+
+ <para>Upgrade from any release prior to 1.0.0RC6 requires an <link
+ linkend="hard_upgrade">hard upgrade</link>.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Memory leak plugged in GiST indexing</para>
+
+ <para>Segfault fix in transform() handling of proj4 errors</para>
+
+ <para>Fixed some proj4 texts in spatial_ref_sys (missing +proj)</para>
+
+ <para>Loader: fixed string functions usage, reworked NULL objects
+ check, fixed segfault on MULTILINESTRING input.</para>
+
+ <para>Fixed bug in MakeLine dimension handling</para>
+
+ <para>Fixed bug in translate() corrupting output bounding box</para>
+ </sect3>
+
+ <sect3>
+ <title>Improvements</title>
+
+ <para>Documentation improvements</para>
+
+ <para>More robust selectivity estimator</para>
+
+ <para>Minor speedup in distance()</para>
+
+ <para>Minor cleanups</para>
+
+ <para>GiST indexing cleanup</para>
+
+ <para>Looser syntax acceptance in box3d parser</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="rel_1.0.3_upgrading">
+ <title>Release 1.0.3</title>
+
+ <para>Release date: 2005/08/08</para>
+
+ <para>Contains some bug fixes - <emphasis>including a severe one
+ affecting correctness of stored geometries</emphasis> - and a few
+ improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>Due to a bug in a bounding box computation routine, the upgrade
+ procedure requires special attention, as bounding boxes cached in the
+ database could be incorrect.</para>
+
+ <para>An <link linkend="hard_upgrade">hard upgrade</link> procedure
+ (dump/reload) will force recomputation of all bounding boxes (not
+ included in dumps). This is <emphasis>required</emphasis> if upgrading
+ from releases prior to 1.0.0RC6.</para>
+
+ <para>If you are upgrading from versions 1.0.0RC6 or up, this release
+ includes a perl script (utils/rebuild_bbox_caches.pl) to force
+ recomputation of geometries' bounding boxes and invoke all operations
+ required to propagate eventual changes in them (geometry statistics
+ update, reindexing). Invoke the script after a make install (run with
+ no args for syntax help). Optionally run utils/postgis_proc_upgrade.pl
+ to refresh postgis procedures and functions signatures (see <link
+ linkend="soft_upgrade">Soft upgrade</link>).</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Severe bugfix in lwgeom's 2d bounding box computation</para>
+
+ <para>Bugfix in WKT (-w) POINT handling in loader</para>
+
+ <para>Bugfix in dumper on 64bit machines</para>
+
+ <para>Bugfix in dumper handling of user-defined queries</para>
+
+ <para>Bugfix in create_undef.pl script</para>
+ </sect3>
+
+ <sect3>
+ <title>Improvements</title>
+
+ <para>Small performance improvement in canonical input function</para>
+
+ <para>Minor cleanups in loader</para>
+
+ <para>Support for multibyte field names in loader</para>
+
+ <para>Improvement in the postgis_restore.pl script</para>
+
+ <para>New rebuild_bbox_caches.pl util script</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.2</title>
+
+ <para>Release date: 2005/07/04</para>
+
+ <para>Contains a few bug fixes and improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.0RC6 or up you
+ <emphasis>DO NOT</emphasis> need a dump/reload.</para>
+
+ <para>Upgrading from older releases requires a dump/reload. See the
+ <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Bug fixes</title>
+
+ <para>Fault tolerant btree ops</para>
+
+ <para>Memory leak plugged in pg_error</para>
+
+ <para>Rtree index fix</para>
+
+ <para>Cleaner build scripts (avoided mix of CFLAGS and
+ CXXFLAGS)</para>
+ </sect3>
+
+ <sect3>
+ <title>Improvements</title>
+
+ <para>New index creation capabilities in loader (-I switch)</para>
+
+ <para>Initial support for postgresql 8.1dev</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.1</title>
+
+ <para>Release date: 2005/05/24</para>
+
+ <para>Contains a few bug fixes and some improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.0RC6 or up you
+ <emphasis>DO NOT</emphasis> need a dump/reload.</para>
+
+ <para>Upgrading from older releases requires a dump/reload. See the
+ <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX in 3d computation of length_spheroid()</para>
+
+ <para>BUGFIX in join selectivity estimator</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes/additions</title>
+
+ <para>BUGFIX in shp2pgsql escape functions</para>
+
+ <para>better support for concurrent postgis in multiple schemas</para>
+
+ <para>documentation fixes</para>
+
+ <para>jdbc2: compile with "-target 1.2 -source 1.2" by default</para>
+
+ <para>NEW -k switch for pgsql2shp</para>
+
+ <para>NEW support for custom createdb options in
+ postgis_restore.pl</para>
+
+ <para>BUGFIX in pgsql2shp attribute names unicity enforcement</para>
+
+ <para>BUGFIX in Paris projections definitions</para>
+
+ <para>postgis_restore.pl cleanups</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0</title>
+
+ <para>Release date: 2005/04/19</para>
+
+ <para>Final 1.0.0 release. Contains a few bug fixes, some improvements
+ in the loader (most notably support for older postgis versions), and
+ more docs.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.0RC6 you <emphasis>DO
+ NOT</emphasis> need a dump/reload.</para>
+
+ <para>Upgrading from any other precedent release requires a
+ dump/reload. See the <link linkend="upgrading">upgrading</link>
+ chapter for more informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX in transform() releasing random memory address</para>
+
+ <para>BUGFIX in force_3dm() allocating less memory then
+ required</para>
+
+ <para>BUGFIX in join selectivity estimator (defaults, leaks,
+ tuplecount, sd)</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes/additions</title>
+
+ <para>BUGFIX in shp2pgsql escape of values starting with tab or
+ single-quote</para>
+
+ <para>NEW manual pages for loader/dumper</para>
+
+ <para>NEW shp2pgsql support for old (HWGEOM) postgis versions</para>
+
+ <para>NEW -p (prepare) flag for shp2pgsql</para>
+
+ <para>NEW manual chapter about OGC compliancy enforcement</para>
+
+ <para>NEW autoconf support for JTS lib</para>
+
+ <para>BUGFIX in estimator testers (support for LWGEOM and schema
+ parsing)</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC6</title>
+
+ <para>Release date: 2005/03/30</para>
+
+ <para>Sixth release candidate for 1.0.0. Contains a few bug fixes and
+ cleanups.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>You need a dump/reload to upgrade from precedent releases. See
+ the <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX in multi()</para>
+
+ <para>early return [when noop] from multi()</para>
+ </sect3>
+
+ <sect3>
+ <title>Scripts changes</title>
+
+ <para>dropped {x,y}{min,max}(box2d) functions</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>BUGFIX in postgis_restore.pl scrip</para>
+
+ <para>BUGFIX in dumper's 64bit support</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC5</title>
+
+ <para>Release date: 2005/03/25</para>
+
+ <para>Fifth release candidate for 1.0.0. Contains a few bug fixes and a
+ improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>If you are upgrading from release 1.0.0RC4 you <emphasis>DO
+ NOT</emphasis> need a dump/reload.</para>
+
+ <para>Upgrading from any other precedent release requires a
+ dump/reload. See the <link linkend="upgrading">upgrading</link>
+ chapter for more informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX (segfaulting) in box3d computation (yes,
+ another!).</para>
+
+ <para>BUGFIX (segfaulting) in estimated_extent().</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>Small build scripts and utilities refinements.</para>
+
+ <para>Additional performance tips documented.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC4</title>
+
+ <para>Release date: 2005/03/18</para>
+
+ <para>Fourth release candidate for 1.0.0. Contains bug fixes and a few
+ improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>You need a dump/reload to upgrade from precedent releases. See
+ the <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX (segfaulting) in geom_accum().</para>
+
+ <para>BUGFIX in 64bit architectures support.</para>
+
+ <para>BUGFIX in box3d computation function with collections.</para>
+
+ <para>NEW subselects support in selectivity estimator.</para>
+
+ <para>Early return from force_collection.</para>
+
+ <para>Consistency check fix in SnapToGrid().</para>
+
+ <para>Box2d output changed back to 15 significant digits.</para>
+ </sect3>
+
+ <sect3>
+ <title>Scripts changes</title>
+
+ <para>NEW distance_sphere() function.</para>
+
+ <para>Changed get_proj4_from_srid implementation to use PL/PGSQL
+ instead of SQL.</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>BUGFIX in loader and dumper handling of MultiLine shapes</para>
+
+ <para>BUGFIX in loader, skipping all but first hole of
+ polygons.</para>
+
+ <para>jdbc2: code cleanups, Makefile improvements</para>
+
+ <para>FLEX and YACC variables set *after* pgsql Makefile.global is
+ included and only if the pgsql *stripped* version evaluates to the
+ empty string</para>
+
+ <para>Added already generated parser in release</para>
+
+ <para>Build scripts refinements</para>
+
+ <para>improved version handling, central Version.config</para>
+
+ <para>improvements in postgis_restore.pl</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC3</title>
+
+ <para>Release date: 2005/02/24</para>
+
+ <para>Third release candidate for 1.0.0. Contains many bug fixes and
+ improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>You need a dump/reload to upgrade from precedent releases. See
+ the <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX in transform(): missing SRID, better error
+ handling.</para>
+
+ <para>BUGFIX in memory alignment handling</para>
+
+ <para>BUGFIX in force_collection() causing mapserver connector
+ failures on simple (single) geometry types.</para>
+
+ <para>BUGFIX in GeometryFromText() missing to add a bbox cache.</para>
+
+ <para>reduced precision of box2d output.</para>
+
+ <para>prefixed DEBUG macros with PGIS_ to avoid clash with pgsql
+ one</para>
+
+ <para>plugged a leak in GEOS2POSTGIS converter</para>
+
+ <para>Reduced memory usage by early releasing query-context palloced
+ one.</para>
+ </sect3>
+
+ <sect3>
+ <title>Scripts changes</title>
+
+ <para>BUGFIX in 72 index bindings.</para>
+
+ <para>BUGFIX in probe_geometry_columns() to work with PG72 and support
+ multiple geometry columns in a single table</para>
+
+ <para>NEW bool::text cast</para>
+
+ <para>Some functions made IMMUTABLE from STABLE, for performance
+ improvement.</para>
+ </sect3>
+
+ <sect3>
+ <title>JDBC changes</title>
+
+ <para>jdbc2: small patches, box2d/3d tests, revised docs and
+ license.</para>
+
+ <para>jdbc2: bug fix and testcase in for pgjdbc 8.0 type
+ autoregistration</para>
+
+ <para>jdbc2: Removed use of jdk1.4 only features to enable build with
+ older jdk releases.</para>
+
+ <para>jdbc2: Added support for building against pg72jdbc2.jar</para>
+
+ <para>jdbc2: updated and cleaned makefile</para>
+
+ <para>jdbc2: added BETA support for jts geometry classes</para>
+
+ <para>jdbc2: Skip known-to-fail tests against older PostGIS
+ servers.</para>
+
+ <para>jdbc2: Fixed handling of measured geometries in EWKT.</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>new performance tips chapter in manual</para>
+
+ <para>documentation updates: pgsql72 requirement, lwpostgis.sql</para>
+
+ <para>few changes in autoconf</para>
+
+ <para>BUILDDATE extraction made more portable</para>
+
+ <para>fixed spatial_ref_sys.sql to avoid vacuuming the whole
+ database.</para>
+
+ <para>spatial_ref_sys: changed Paris entries to match the ones
+ distributed with 0.x.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC2</title>
+
+ <para>Release date: 2005/01/26</para>
+
+ <para>Second release candidate for 1.0.0 containing bug fixes and a few
+ improvements.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>You need a dump/reload to upgrade from precedent releases. See
+ the <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Library changes</title>
+
+ <para>BUGFIX in pointarray box3d computation</para>
+
+ <para>BUGFIX in distance_spheroid definition</para>
+
+ <para>BUGFIX in transform() missing to update bbox cache</para>
+
+ <para>NEW jdbc driver (jdbc2)</para>
+
+ <para>GEOMETRYCOLLECTION(EMPTY) syntax support for backward
+ compatibility</para>
+
+ <para>Faster binary outputs</para>
+
+ <para>Stricter OGC WKB/WKT constructors</para>
+ </sect3>
+
+ <sect3>
+ <title>Scripts changes</title>
+
+ <para>More correct STABLE, IMMUTABLE, STRICT uses in
+ lwpostgis.sql</para>
+
+ <para>stricter OGC WKB/WKT constructors</para>
+ </sect3>
+
+ <sect3>
+ <title>Other changes</title>
+
+ <para>Faster and more robust loader (both i18n and not)</para>
+
+ <para>Initial autoconf script</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Release 1.0.0RC1</title>
+
+ <para>Release date: 2005/01/13</para>
+
+ <para>This is the first candidate of a major postgis release, with
+ internal storage of postgis types redesigned to be smaller and faster on
+ indexed queries.</para>
+
+ <sect3>
+ <title>Upgrading</title>
+
+ <para>You need a dump/reload to upgrade from precedent releases. See
+ the <link linkend="upgrading">upgrading</link> chapter for more
+ informations.</para>
+ </sect3>
+
+ <sect3>
+ <title>Changes</title>
+
+ <para>Faster canonical input parsing.</para>
+
+ <para>Lossless canonical output.</para>
+
+ <para>EWKB Canonical binary IO with PG>73.</para>
+
+ <para>Support for up to 4d coordinates, providing lossless
+ shapefile->postgis->shapefile conversion.</para>
+
+ <para>New function: UpdateGeometrySRID(), AsGML(), SnapToGrid(),
+ ForceRHR(), estimated_extent(), accum().</para>
+
+ <para>Vertical positioning indexed operators.</para>
+
+ <para>JOIN selectivity function.</para>
+
+ <para>More geometry constructors / editors.</para>
+
+ <para>PostGIS extension API.</para>
+
+ <para>UTF8 support in loader.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+</appendix>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Reporting Problems</title>
+
+ <sect1>
+ <title>Reporting Software Bugs</title>
+
+ <para>Reporting bugs effectively is a fundamental way to help PostGIS
+ development. The most effective bug report is that enabling PostGIS
+ developers to reproduce it, so it would ideally contain a script
+ triggering it and every information regarding the environment in which it
+ was detected. Good enough info can be extracted running <code>SELECT
+ postgis_full_version()</code> [for postgis] and <code>SELECT
+ version()</code> [for postgresql].</para>
+
+ <para>If you aren't using the latest release, it's worth taking a look at
+ its <ulink url="http://postgis.refractions.net/CHANGES.txt">release
+ changelog</ulink> first, to find out if your bug has already been
+ fixed.</para>
+
+ <para>Using the <ulink
+ url="http://code.google.com/p/postgis/issues/list">PostGIS bug
+ tracker</ulink> will ensure your reports are not discarded, and will keep
+ you informed on its handling process. Before reporting a new bug please
+ query the database to see if it is a known one, and if it is please add
+ any new information you have about it.</para>
+
+ <para>You might want to read Simon Tatham's paper about <ulink
+ url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
+ Bugs Effectively</ulink> before filing a new report.</para>
+ </sect1>
+
+ <sect1>
+ <title>Reporting Documentation Issues</title>
+
+ <para>The documentation should accurately reflect the features and
+ behavior of the software. If it doesn't, it could be because of a software
+ bug or because the documentation is in error or deficient.</para>
+
+ <para>Documentation issues can also be reported to the <ulink
+ url="http://code.google.com/p/postgis/issues/list">PostGIS bug
+ tracker</ulink>.</para>
+
+ <para>If your revision is trivial, just describe it in a new bug tracker
+ issue, being specific about its location in the documentation.</para>
+
+ <para>If your changes are more extensive, a Subversion patch is definitely
+ preferred. This is a four step process on Unix (assuming you already have
+ <ulink url="http://subversion.tigris.org/">Subversion</ulink>
+ installed):</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Check out a copy of PostGIS' Subversion trunk. On Unix,
+ type:</para>
+
+ <para><command>svn checkout
+ http://svn.refractions.net/postgis/trunk/</command></para>
+
+ <para>This will be stored in the directory ./trunk</para>
+ </listitem>
+
+ <listitem>
+ <para>Make your changes to the documentation with your favorite text
+ editor. On Unix, type (for example):</para>
+
+ <para><command>vi trunk/doc/postgis.xml</command></para>
+
+ <para>Note that the documentation is written in SGML rather than HTML,
+ so if you are not familiar with it please follow the example of the
+ rest of the documentation.</para>
+ </listitem>
+
+ <listitem>
+ <para>Make a patch file containing the differences from the master
+ copy of the documentation. On Unix, type:</para>
+
+ <para><command>svn diff trunk/doc/postgis.xml >
+ doc.patch</command></para>
+ </listitem>
+
+ <listitem>
+ <para>Attach the patch to a new issue in bug tracker.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+</chapter>
\ No newline at end of file
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter>
+ <title>Using PostGIS</title>
+
+ <sect1 id="RefObject">
+ <title>GIS Objects</title>
+
+ <para>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.</para>
+
+ <para>PostGIS extends the standard with support for 3DZ,3DM and 4D
+ coordinates.</para>
+
+ <sect2>
+ <title>OpenGIS WKB and WKT</title>
+
+ <para>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.</para>
+
+ <para>Examples of the text representations (WKT) of the spatial objects
+ of the features are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>POINT(0 0)</para>
+ </listitem>
+
+ <listitem>
+ <para>LINESTRING(0 0,1 1,1 2)</para>
+ </listitem>
+
+ <listitem>
+ <para>POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTIPOINT(0 0,1 2)</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTILINESTRING((0 0,1 1,1 2),(2 3,3 2,5 4))</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTIPOLYGON(((0 0,4 0,4 4,0 4,0 0),(1 1,2 1,2 2,1 2,1 1)),
+ ((-1 -1,-1 -2,-2 -2,-2 -1,-1 -1)))</para>
+ </listitem>
+
+ <listitem>
+ <para>GEOMETRYCOLLECTION(POINT(2 3),LINESTRING(2 3,3 4))</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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.</para>
+
+ <para>Input/Output of these formats are available using the following
+ interfaces:</para>
+
+ <programlisting>bytea WKB = asBinary(geometry);
+text WKT = asText(geometry);
+geometry = GeomFromWKB(bytea WKB, SRID);
+geometry = GeometryFromText(text WKT, SRID);</programlisting>
+
+ <para>For example, a valid insert statement to create and insert an OGC
+ spatial object would be:</para>
+
+ <programlisting>INSERT INTO geotable ( the_geom, the_name )
+ VALUES ( GeomFromText('POINT(-126.4 45.32)', 312), 'A Place');</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>PostGIS EWKB, EWKT and Canonical Forms</title>
+
+ <para>OGC formats only support 2d geometries, and the associated SRID is
+ *never* embedded in the input/output representations.</para>
+
+ <para>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!</para>
+
+ <para>PostGIS EWKB/EWKT add 3dm,3dz,4d coordinates support and embedded
+ SRID information.</para>
+
+ <para>Examples of the text representations (EWKT) of the extended
+ spatial objects of the features are as follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>POINT(0 0 0) -- XYZ</para>
+ </listitem>
+
+ <listitem>
+ <para>SRID=32632;POINT(0 0) -- XY with SRID</para>
+ </listitem>
+
+ <listitem>
+ <para>POINTM(0 0 0) -- XYM</para>
+ </listitem>
+
+ <listitem>
+ <para>POINT(0 0 0 0) -- XYZM</para>
+ </listitem>
+
+ <listitem>
+ <para>SRID=4326;MULTIPOINTM(0 0 0,1 2 1) -- XYM with SRID</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTILINESTRING((0 0 0,1 1 0,1 2 1),(2 3 1,3 2 1,5 4
+ 1))</para>
+ </listitem>
+
+ <listitem>
+ <para>POLYGON((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2 0,1 2
+ 0,1 1 0))</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTIPOLYGON(((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2
+ 0,1 2 0,1 1 0)),((-1 -1 0,-1 -2 0,-2 -2 0,-2 -1 0,-1 -1 0)))</para>
+ </listitem>
+
+ <listitem>
+ <para>GEOMETRYCOLLECTIONM(POINTM(2 3 9), LINESTRINGM(2 3 4, 3 4
+ 5))</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Input/Output of these formats are available using the following
+ interfaces:</para>
+
+ <programlisting>bytea EWKB = asEWKB(geometry);
+text EWKT = asEWKT(geometry);
+geometry = GeomFromEWKB(bytea EWKB);
+geometry = GeomFromEWKT(text EWKT);</programlisting>
+
+ <para>For example, a valid insert statement to create and insert a
+ PostGIS spatial object would be:</para>
+
+ <programlisting>INSERT INTO geotable ( the_geom, the_name )
+ VALUES ( GeomFromEWKT('SRID=312;POINTM(-126.4 45.32 15)'), 'A Place' )</programlisting>
+
+ <para>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: <programlisting>- Output
+ - binary: EWKB
+ ascii: HEXEWKB (EWKB in hex form)
+- Input
+ - binary: EWKB
+ ascii: HEXEWKB|EWKT </programlisting></para>
+
+ <para>For example this statement reads EWKT and returns HEXEWKB in the
+ process of canonical ascii input/output:</para>
+
+ <programlisting>=# SELECT 'SRID=4;POINT(0 0)'::geometry;
+
+geometry
+----------------------------------------------------
+01010000200400000000000000000000000000000000000000
+(1 row)</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>SQL-MM Part 3</title>
+
+ <para>The SQL Multimedia Applications Spatial specification extends the
+ simple features for SQL spec by defining a number of circularly
+ interpolated curves.</para>
+
+ <para>The SQL-MM definitions include 3dm, 3dz and 4d coordinates, but do
+ not allow the embedding of SRID information.</para>
+
+ <para>The well-known text extensions are not yet fully supported.
+ Examples of some simple curved geometries are shown below:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>CIRCULARSTRING(0 0, 1 1, 1 0)</para>
+ </listitem>
+
+ <listitem>
+ <para>COMPOUNDCURVE(CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1))</para>
+ </listitem>
+
+ <listitem>
+ <para>CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3
+ 3, 3 1, 1 1))</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTICURVE((0 0, 5 5),CIRCULARSTRING(4 0, 4 4, 8 4))</para>
+ </listitem>
+
+ <listitem>
+ <para>MULTISURFACE(CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0
+ 0),(1 1, 3 3, 3 1, 1 1)),((10 10, 14 12, 11 10, 10 10),(11 11, 11.5
+ 11, 11 11.5, 11 11)))</para>
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>Currently, PostGIS cannot support the use of Compound Curves in
+ a Curve Polygon.</para>
+ </note>
+
+ <note>
+ <para>All floating point comparisons within the SQL-MM implementation
+ are performed to a specified tolerance, currently 1E-8.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Using OpenGIS Standards</title>
+
+ <para>The OpenGIS "Simple Features Specification for SQL" defines standard
+ GIS object types, the functions required to manipulate them, and a set of
+ meta-data tables. In order to ensure that meta-data remain consistent,
+ operations such as creating and removing a spatial column are carried out
+ through special procedures defined by OpenGIS.</para>
+
+ <para>There are two OpenGIS meta-data tables:
+ <varname>SPATIAL_REF_SYS</varname> and
+ <varname>GEOMETRY_COLUMNS</varname>. The
+ <varname>SPATIAL_REF_SYS</varname> table holds the numeric IDs and textual
+ descriptions of coordinate systems used in the spatial database.</para>
+
+ <sect2>
+ <title>The SPATIAL_REF_SYS Table</title>
+
+ <para>The <varname>SPATIAL_REF_SYS</varname> table definition is as
+ follows:</para>
+
+ <programlisting>CREATE TABLE spatial_ref_sys (
+ srid INTEGER NOT NULL PRIMARY KEY,
+ auth_name VARCHAR(256),
+ auth_srid INTEGER,
+ srtext VARCHAR(2048),
+ proj4text VARCHAR(2048)
+)</programlisting>
+
+ <para>The <varname>SPATIAL_REF_SYS</varname> columns are as
+ follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SRID</term>
+
+ <listitem>
+ <para>An integer value that uniquely identifies the Spatial
+ Referencing System (SRS) within the database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>AUTH_NAME</term>
+
+ <listitem>
+ <para>The name of the standard or standards body that is being
+ cited for this reference system. For example, "EPSG" would be a
+ valid <varname>AUTH_NAME</varname>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>AUTH_SRID</term>
+
+ <listitem>
+ <para>The ID of the Spatial Reference System as defined by the
+ Authority cited in the <varname>AUTH_NAME</varname>. In the case
+ of EPSG, this is where the EPSG projection code would go.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SRTEXT</term>
+
+ <listitem>
+ <para>The Well-Known Text representation of the Spatial Reference
+ System. An example of a WKT SRS representation is:</para>
+
+ <programlisting>PROJCS["NAD83 / UTM Zone 10N",
+ GEOGCS["NAD83",
+ DATUM["North_American_Datum_1983",
+ SPHEROID["GRS 1980",6378137,298.257222101]
+ ],
+ PRIMEM["Greenwich",0],
+ UNIT["degree",0.0174532925199433]
+ ],
+ PROJECTION["Transverse_Mercator"],
+ PARAMETER["latitude_of_origin",0],
+ PARAMETER["central_meridian",-123],
+ PARAMETER["scale_factor",0.9996],
+ PARAMETER["false_easting",500000],
+ PARAMETER["false_northing",0],
+ UNIT["metre",1]
+]</programlisting>
+
+ <para>For a listing of EPSG projection codes and their
+ corresponding WKT representations, see <ulink
+ url="http://www.opengis.org/techno/interop/EPSG2WKT.TXT">http://www.opengis.org/techno/interop/EPSG2WKT.TXT</ulink>.
+ For a discussion of WKT in general, see the OpenGIS "Coordinate
+ Transformation Services Implementation Specification" at <ulink
+ url="http://www.opengis.org/techno/specs.htm">http://www.opengis.org/techno/specs.htm</ulink>.
+ For information on the European Petroleum Survey Group (EPSG) and
+ their database of spatial reference systems, see <ulink
+ url="http://epsg.org">http://epsg.org</ulink>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PROJ4TEXT</term>
+
+ <listitem>
+ <para>PostGIS uses the Proj4 library to provide coordinate
+ transformation capabilities. The <varname>PROJ4TEXT</varname>
+ column contains the Proj4 coordinate definition string for a
+ particular SRID. For example:</para>
+
+ <programlisting>+proj=utm +zone=10 +ellps=clrk66 +datum=NAD27 +units=m</programlisting>
+
+ <para>For more information about, see the Proj4 web site at <ulink
+ url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.
+ The <filename>spatial_ref_sys.sql</filename> file contains both
+ <varname>SRTEXT</varname> and <varname>PROJ4TEXT</varname>
+ definitions for all EPSG projections.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>The GEOMETRY_COLUMNS Table</title>
+
+ <para>The <varname>GEOMETRY_COLUMNS</varname> table definition is as
+ follows:</para>
+
+ <programlisting>CREATE TABLE geometry_columns (
+ f_table_catalog VARRCHAR(256) NOT NULL,
+ f_table_schema VARCHAR(256) NOT NULL,
+ f_table_nam VARCHAR(256) NOT NULL,
+ f_geometry_column VARCHAR(256) NOT NULL,
+ coord_dimension INTEGER NOT NULL,
+ srid INTEGER NOT NULL,
+ type VARCHAR(30) NOT NULL
+)</programlisting>
+
+ <para>The columns are as follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>F_TABLE_CATALOG, F_TABLE_SCHEMA, F_TABLE_NAME</term>
+
+ <listitem>
+ <para>The fully qualified name of the feature table containing the
+ geometry column. Note that the terms "catalog" and "schema" are
+ Oracle-ish. There is not PostgreSQL analogue of "catalog" so that
+ column is left blank -- for "schema" the PostgreSQL schema name is
+ used (<varname>public</varname> is the default).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>F_GEOMETRY_COLUMN</term>
+
+ <listitem>
+ <para>The name of the geometry column in the feature table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>COORD_DIMENSION</term>
+
+ <listitem>
+ <para>The spatial dimension (2, 3 or 4 dimensional) of the
+ column.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SRID</term>
+
+ <listitem>
+ <para>The ID of the spatial reference system used for the
+ coordinate geometry in this table. It is a foreign key reference
+ to the <varname>SPATIAL_REF_SYS</varname>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>TYPE</term>
+
+ <listitem>
+ <para>The type of the spatial object. To restrict the spatial
+ column to a single type, use one of: POINT, LINESTRING, POLYGON,
+ MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION or
+ corresponding XYM versions POINTM, LINESTRINGM, POLYGONM,
+ MULTIPOINTM, MULTILINESTRINGM, MULTIPOLYGONM, GEOMETRYCOLLECTIONM.
+ For heterogeneous (mixed-type) collections, you can use "GEOMETRY"
+ as the type.</para>
+
+ <note>
+ <para>This attribute is (probably) not part of the OpenGIS
+ specification, but is required for ensuring type
+ homogeneity.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Creating a Spatial Table</title>
+
+ <para>Creating a table with spatial data is done in two stages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Create a normal non-spatial table.</para>
+
+ <para>For example: <command>CREATE TABLE ROADS_GEOM ( ID int4, NAME
+ varchar(25) )</command></para>
+ </listitem>
+
+ <listitem>
+ <para>Add a spatial column to the table using the OpenGIS
+ "AddGeometryColumn" function.</para>
+
+ <para>The syntax is: <programlisting>AddGeometryColumn(
+ <schema_name>,
+ <table_name>,
+ <column_name>,
+ <srid>,
+ <type>,
+ <dimension>
+)</programlisting> Or, using current schema: <programlisting>AddGeometryColumn(
+ <table_name>,
+ <column_name>,
+ <srid>,
+ <type>,
+ <dimension>
+)</programlisting></para>
+
+ <para>Example1: <command>SELECT AddGeometryColumn('public',
+ 'roads_geom', 'geom', 423, 'LINESTRING', 2)</command></para>
+
+ <para>Example2: <command>SELECT AddGeometryColumn( 'roads_geom',
+ 'geom', 423, 'LINESTRING', 2)</command></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Here is an example of SQL used to create a table and add a spatial
+ column (assuming that an SRID of 128 exists already):</para>
+
+ <programlisting>CREATE TABLE parks (
+ park_id INTEGER,
+ park_name VARCHAR,
+ park_date DATE,
+ park_type VARCHAR
+);
+SELECT AddGeometryColumn('parks', 'park_geom', 128, 'MULTIPOLYGON', 2 );</programlisting>
+
+ <para>Here is another example, using the generic "geometry" type and the
+ undefined SRID value of -1:</para>
+
+ <programlisting>CREATE TABLE roads (
+ road_id INTEGER,
+ road_name VARCHAR
+);
+SELECT AddGeometryColumn( 'roads', 'roads_geom', -1, 'GEOMETRY', 3 );</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Ensuring OpenGIS compliancy of geometries</title>
+
+ <para>Most of the functions implemented by the GEOS library rely on the
+ assumption that your geometries are valid as specified by the OpenGIS
+ Simple Feature Specification. To check validity of geometries you can
+ use the <link linkend="IsValid">IsValid()</link> function:</para>
+
+ <programlisting> gisdb=# select isvalid('LINESTRING(0 0, 1 1)'),
+ isvalid('LINESTRING(0 0,0 0)');
+
+ isvalid | isvalid
+---------+---------
+ t | f</programlisting>
+
+ <para>By default, PostGIS does not apply this validity check on geometry
+ input, because testing for validity needs lots of CPU time for complex
+ geometries, especially polygons. If you do not trust your data sources,
+ you can manually enforce such a check to your tables by adding a check
+ constraint:</para>
+
+ <programlisting>ALTER TABLE mytable
+ ADD CONSTRAINT geometry_valid_check
+ CHECK (isvalid(the_geom));</programlisting>
+
+ <para>If you encounter any strange error messages such as "GEOS
+ Intersection() threw an error!" or "JTS Intersection() threw an error!"
+ when calling PostGIS functions with valid input geometries, you likely
+ found an error in either PostGIS or one of the libraries it uses, and
+ you should contact the PostGIS developers. The same is true if a PostGIS
+ function returns an invalid geometry for valid input.</para>
+
+ <note>
+ <para>Strictly compliant OGC geometries cannot have Z or M values. The
+ <link linkend="IsValid">IsValid()</link> function won't consider
+ higher dimensioned geometries invalid! Invocations of <link
+ linkend="AddGeometryColumn">AddGeometryColumn()</link> will add a
+ constraint checking geometry dimensions, so it is enough to specify 2
+ there.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Loading GIS Data</title>
+
+ <para>Once you have created a spatial table, you are ready to upload GIS
+ data to the database. Currently, there are two ways to get data into a
+ PostGIS/PostgreSQL database: using formatted SQL statements or using the
+ Shape file loader/dumper.</para>
+
+ <sect2>
+ <title>Using SQL</title>
+
+ <para>If you can convert your data to a text representation, then using
+ formatted SQL might be the easiest way to get your data into PostGIS. As
+ with Oracle and other SQL databases, data can be bulk loaded by piping a
+ large text file full of SQL "INSERT" statements into the SQL terminal
+ monitor.</para>
+
+ <para>A data upload file (<filename>roads.sql</filename> for example)
+ might look like this:</para>
+
+ <programlisting>BEGIN;
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (1,GeomFromText('LINESTRING(191232 243118,191108 243242)',-1),'Jeff Rd');
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (2,GeomFromText('LINESTRING(189141 244158,189265 244817)',-1),'Geordie Rd');
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (3,GeomFromText('LINESTRING(192783 228138,192612 229814)',-1),'Paul St');
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (4,GeomFromText('LINESTRING(189412 252431,189631 259122)',-1),'Graeme Ave');
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (5,GeomFromText('LINESTRING(190131 224148,190871 228134)',-1),'Phil Tce');
+INSERT INTO roads (road_id, roads_geom, road_name)
+ VALUES (6,GeomFromText('LINESTRING(198231 263418,198213 268322)',-1),'Dave Cres');
+COMMIT;</programlisting>
+
+ <para>The data file can be piped into PostgreSQL very easily using the
+ "psql" SQL terminal monitor:</para>
+
+ <programlisting>psql -d [database] -f roads.sql</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>Using the Loader</title>
+
+ <para>The <filename>shp2pgsql</filename> data loader converts ESRI Shape
+ files into SQL suitable for insertion into a PostGIS/PostgreSQL
+ database. The loader has several operating modes distinguished by
+ command line flags:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>-d</term>
+
+ <listitem>
+ <para>Drops the database table before creating a new table with
+ the data in the Shape file.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-a</term>
+
+ <listitem>
+ <para>Appends data from the Shape file into the database table.
+ Note that to use this option to load multiple files, the files
+ must have the same attributes and same data types.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-c</term>
+
+ <listitem>
+ <para>Creates a new table and populates it from the Shape file.
+ <emphasis>This is the default mode.</emphasis></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p</term>
+
+ <listitem>
+ <para>Only produces the table creation SQL code, without adding
+ any actual data. This can be used if you need to completely
+ separate the table creation and data loading steps.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-D</term>
+
+ <listitem>
+ <para>Use the PostgreSQL "dump" format for the output data. This
+ can be combined with -a, -c and -d. It is much faster to load than
+ the default "insert" SQL format. Use this for very large data
+ sets.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-s <SRID></term>
+
+ <listitem>
+ <para>Creates and populates the geometry tables with the specified
+ SRID.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-k</term>
+
+ <listitem>
+ <para>Keep identifiers' case (column, schema and attributes). Note
+ that attributes in Shapefile are all UPPERCASE.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-i</term>
+
+ <listitem>
+ <para>Coerce all integers to standard 32-bit integers, do not
+ create 64-bit bigints, even if the DBF header signature appears to
+ warrant it.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-I</term>
+
+ <listitem>
+ <para>Create a GiST index on the geometry column.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-w</term>
+
+ <listitem>
+ <para>Output WKT format, for use with older (0.x) versions of
+ PostGIS. Note that this will introduce coordinate drifts and will
+ drop M values from shapefiles.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-W <encoding></term>
+
+ <listitem>
+ <para>Specify encoding of the input data (dbf file). When used,
+ all attributes of the dbf are converted from the specified
+ encoding to UTF8. The resulting SQL output will contain a
+ <code>SET CLIENT_ENCODING to UTF8</code> command, so that the
+ backend will be able to reconvert from UTF8 to whatever encoding
+ the database is configured to use internally.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Note that -a, -c, -d and -p are mutually exclusive.</para>
+
+ <para>An example session using the loader to create an input file and
+ uploading it might look like this:</para>
+
+ <programlisting># shp2pgsql shaperoads myschema.roadstable > roads.sql
+# psql -d roadsdb -f roads.sql</programlisting>
+
+ <para>A conversion and upload can be done all in one step using UNIX
+ pipes:</para>
+
+ <programlisting># shp2pgsql shaperoads myschema.roadstable | psql -d roadsdb</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Retrieving GIS Data</title>
+
+ <para>Data can be extracted from the database using either SQL or the
+ Shape file loader/dumper. In the section on SQL we will discuss some of
+ the operators available to do comparisons and queries on spatial
+ tables.</para>
+
+ <sect2>
+ <title>Using SQL</title>
+
+ <para>The most straightforward means of pulling data out of the database
+ is to use a SQL select query and dump the resulting columns into a
+ parsable text file:</para>
+
+ <programlisting>db=# SELECT road_id, AsText(road_geom) AS geom, road_name FROM roads;
+
+road_id | geom | road_name
+--------+-----------------------------------------+-----------
+ 1 | LINESTRING(191232 243118,191108 243242) | Jeff Rd
+ 2 | LINESTRING(189141 244158,189265 244817) | Geordie Rd
+ 3 | LINESTRING(192783 228138,192612 229814) | Paul St
+ 4 | LINESTRING(189412 252431,189631 259122) | Graeme Ave
+ 5 | LINESTRING(190131 224148,190871 228134) | Phil Tce
+ 6 | LINESTRING(198231 263418,198213 268322) | Dave Cres
+ 7 | LINESTRING(218421 284121,224123 241231) | Chris Way
+(6 rows)</programlisting>
+
+ <para>However, there will be times when some kind of restriction is
+ necessary to cut down the number of fields returned. In the case of
+ attribute-based restrictions, just use the same SQL syntax as normal
+ with a non-spatial table. In the case of spatial restrictions, the
+ following operators are available/useful:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>&&</term>
+
+ <listitem>
+ <para>This operator tells whether the bounding box of one geometry
+ intersects the bounding box of another.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>~=</term>
+
+ <listitem>
+ <para>This operators tests whether two geometries are
+ geometrically identical. For example, if 'POLYGON((0 0,1 1,1 0,0
+ 0))' is the same as 'POLYGON((0 0,1 1,1 0,0 0))' (it is).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>=</term>
+
+ <listitem>
+ <para>This operator is a little more naive, it only tests whether
+ the bounding boxes of to geometries are the same.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Next, you can use these operators in queries. Note that when
+ specifying geometries and boxes on the SQL command line, you must
+ explicitly turn the string representations into geometries by using the
+ "GeomFromText()" function. So, for example:</para>
+
+ <programlisting>SELECT road_id, road_name
+ FROM roads
+ WHERE roads_geom ~= GeomFromText('LINESTRING(191232 243118,191108 243242)',-1);</programlisting>
+
+ <para>The above query would return the single record from the
+ "ROADS_GEOM" table in which the geometry was equal to that value.</para>
+
+ <para>When using the "&&" operator, you can specify either a
+ BOX3D as the comparison feature or a GEOMETRY. When you specify a
+ GEOMETRY, however, its bounding box will be used for the
+ comparison.</para>
+
+ <programlisting>SELECT road_id, road_name
+FROM roads
+WHERE roads_geom && GeomFromText('POLYGON((...))',-1);</programlisting>
+
+ <para>The above query will use the bounding box of the polygon for
+ comparison purposes.</para>
+
+ <para>The most common spatial query will probably be a "frame-based"
+ query, used by client software, like data browsers and web mappers, to
+ grab a "map frame" worth of data for display. Using a "BOX3D" object for
+ the frame, such a query looks like this:</para>
+
+ <programlisting>SELECT AsText(roads_geom) AS geom
+FROM roads
+WHERE
+ roads_geom && SetSRID('BOX3D(191232 243117,191232 243119)'::box3d,-1);</programlisting>
+
+ <para>Note the use of the SRID, to specify the projection of the BOX3D.
+ The value -1 is used to indicate no specified SRID.</para>
+ </sect2>
+
+ <sect2>
+ <title>Using the Dumper</title>
+
+ <para>The <filename>pgsql2shp</filename> table dumper connects directly
+ to the database and converts a table (possibly defined by a query) into
+ a shape file. The basic syntax is:</para>
+
+ <programlisting>pgsql2shp [<options>] <database> [<schema>.]<table></programlisting>
+
+ <programlisting>pgsql2shp [<options>] <database> <query></programlisting>
+
+ <para>The commandline options are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>-f <filename></term>
+
+ <listitem>
+ <para>Write the output to a particular filename.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-h <host></term>
+
+ <listitem>
+ <para>The database host to connect to.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-p <port></term>
+
+ <listitem>
+ <para>The port to connect to on the database host.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-P <password></term>
+
+ <listitem>
+ <para>The password to use when connecting to the database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-u <user></term>
+
+ <listitem>
+ <para>The username to use when connecting to the database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-g <geometry column></term>
+
+ <listitem>
+ <para>In the case of tables with multiple geometry columns, the
+ geometry column to use when writing the shape file.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-b</term>
+
+ <listitem>
+ <para>Use a binary cursor. This will make the operation faster,
+ but will not work if any NON-geometry attribute in the table lacks
+ a cast to text.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-r</term>
+
+ <listitem>
+ <para>Raw mode. Do not drop the <varname>gid</varname> field, or
+ escape column names.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-d</term>
+
+ <listitem>
+ <para>For backward compatibility: write a 3-dimensional shape file
+ when dumping from old (pre-1.0.0) postgis databases (the default
+ is to write a 2-dimensional shape file in that case). Starting
+ from postgis-1.0.0+, dimensions are fully encoded.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Building Indexes</title>
+
+ <para>Indexes are what make using a spatial database for large data sets
+ possible. Without indexing, any search for a feature would require a
+ "sequential scan" of every record in the database. Indexing speeds up
+ searching by organizing the data into a search tree which can be quickly
+ traversed to find a particular record. PostgreSQL supports three kinds of
+ indexes by default: B-Tree indexes, R-Tree indexes, and GiST
+ indexes.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>B-Trees are used for data which can be sorted along one axis;
+ for example, numbers, letters, dates. GIS data cannot be rationally
+ sorted along one axis (which is greater, (0,0) or (0,1) or (1,0)?) so
+ B-Tree indexing is of no use for us.</para>
+ </listitem>
+
+ <listitem>
+ <para>R-Trees break up data into rectangles, and sub-rectangles, and
+ sub-sub rectangles, etc. R-Trees are used by some spatial databases to
+ index GIS data, but the PostgreSQL R-Tree implementation is not as
+ robust as the GiST implementation.</para>
+ </listitem>
+
+ <listitem>
+ <para>GiST (Generalized Search Trees) indexes break up data into
+ "things to one side", "things which overlap", "things which are
+ inside" and can be used on a wide range of data-types, including GIS
+ data. PostGIS uses an R-Tree index implemented on top of GiST to index
+ GIS data.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2>
+ <title>GiST Indexes</title>
+
+ <para>GiST stands for "Generalized Search Tree" and is a generic form of
+ indexing. In addition to GIS indexing, GiST is used to speed up searches
+ on all kinds of irregular data structures (integer arrays, spectral
+ data, etc) which are not amenable to normal B-Tree indexing.</para>
+
+ <para>Once a GIS data table exceeds a few thousand rows, you will want
+ to build an index to speed up spatial searches of the data (unless all
+ your searches are based on attributes, in which case you'll want to
+ build a normal index on the attribute fields).</para>
+
+ <para>The syntax for building a GiST index on a "geometry" column is as
+ follows:</para>
+
+ <para><programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometryfield] ); </programlisting></para>
+
+ <para>Building a spatial index is a computationally intensive exercise:
+ on tables of around 1 million rows, on a 300MHz Solaris machine, we have
+ found building a GiST index takes about 1 hour. After building an index,
+ it is important to force PostgreSQL to collect table statistics, which
+ are used to optimize query plans:</para>
+
+ <para><programlisting>VACUUM ANALYZE [table_name] [column_name];
+-- This is only needed for PostgreSQL 7.4 installations and below
+SELECT UPDATE_GEOMETRY_STATS([table_name], [column_name]);</programlisting></para>
+
+ <para>GiST indexes have two advantages over R-Tree indexes in
+ PostgreSQL. Firstly, GiST indexes are "null safe", meaning they can
+ index columns which include null values. Secondly, GiST indexes support
+ the concept of "lossiness" which is important when dealing with GIS
+ objects larger than the PostgreSQL 8K page size. Lossiness allows
+ PostgreSQL to store only the "important" part of an object in an index
+ -- in the case of GIS objects, just the bounding box. GIS objects larger
+ than 8K will cause R-Tree indexes to fail in the process of being
+ built.</para>
+ </sect2>
+
+ <sect2>
+ <title>Using Indexes</title>
+
+ <para>Ordinarily, indexes invisibly speed up data access: once the index
+ is built, the query planner transparently decides when to use index
+ information to speed up a query plan. Unfortunately, the PostgreSQL
+ query planner does not optimize the use of GiST indexes well, so
+ sometimes searches which should use a spatial index instead default to a
+ sequence scan of the whole table.</para>
+
+ <para>If you find your spatial indexes are not being used (or your
+ attribute indexes, for that matter) there are a couple things you can
+ do:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Firstly, make sure statistics are gathered about the number
+ and distributions of values in a table, to provide the query planner
+ with better information to make decisions around index usage. For
+ PostgreSQL 7.4 installations and below this is done by running
+ <command>update_geometry_stats([table_name, column_name])</command>
+ (compute distribution) and <command>VACUUM ANALYZE [table_name]
+ [column_name]</command> (compute number of values). Starting with
+ PostgreSQL 8.0 running <command>VACUUM ANALYZE</command> will do
+ both operations. You should regularly vacuum your databases anyways
+ -- many PostgreSQL DBAs have <command>VACUUM</command> run as an
+ off-peak cron job on a regular basis.</para>
+ </listitem>
+
+ <listitem>
+ <para>If vacuuming does not work, you can force the planner to use
+ the index information by using the <command>SET
+ ENABLE_SEQSCAN=OFF</command> command. You should only use this
+ command sparingly, and only on spatially indexed queries: generally
+ speaking, the planner knows better than you do about when to use
+ normal B-Tree indexes. Once you have run your query, you should
+ consider setting <varname>ENABLE_SEQSCAN</varname> back on, so that
+ other queries will utilize the planner as normal.</para>
+
+ <note>
+ <para>As of version 0.6, it should not be necessary to force the
+ planner to use the index with
+ <varname>ENABLE_SEQSCAN</varname>.</para>
+ </note>
+ </listitem>
+
+ <listitem>
+ <para>If you find the planner wrong about the cost of sequential vs
+ index scans try reducing the value of random_page_cost in
+ postgresql.conf or using SET random_page_cost=#. Default value for
+ the parameter is 4, try setting it to 1 or 2. Decrementing the value
+ makes the planner more inclined of using Index scans.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Complex Queries</title>
+
+ <para>The <emphasis>raison d'etre</emphasis> of spatial database
+ functionality is performing queries inside the database which would
+ ordinarily require desktop GIS functionality. Using PostGIS effectively
+ requires knowing what spatial functions are available, and ensuring that
+ appropriate indexes are in place to provide good performance.</para>
+
+ <sect2>
+ <title>Taking Advantage of Indexes</title>
+
+ <para>When constructing a query it is important to remember that only
+ the bounding-box-based operators such as && can take advantage
+ of the GiST spatial index. Functions such as
+ <varname>distance()</varname> cannot use the index to optimize their
+ operation. For example, the following query would be quite slow on a
+ large table:</para>
+
+ <programlisting>SELECT the_geom
+FROM geom_table
+WHERE ST_Distance(the_geom, GeomFromText('POINT(100000 200000)', -1)) < 100</programlisting>
+
+ <para>This query is selecting all the geometries in geom_table which are
+ within 100 units of the point (100000, 200000). It will be slow because
+ it is calculating the distance between each point in the table and our
+ specified point, ie. one <varname>ST_Distance()</varname> calculation
+ for each row in the table. We can avoid this by using the &&
+ operator to reduce the number of distance calculations required:</para>
+
+ <programlisting>SELECT the_geom
+FROM geom_table
+WHERE the_geom && 'BOX3D(90900 190900, 100100 200100)'::box3d
+ AND
+ST_Distance(the_geom, GeomFromText('POINT(100000 200000)', -1)) < 100</programlisting>
+
+ <para>This query selects the same geometries, but it does it in a more
+ efficient way. Assuming there is a GiST index on the_geom, the query
+ planner will recognize that it can use the index to reduce the number of
+ rows before calculating the result of the <varname>distance()</varname>
+ function. Notice that the <varname>BOX3D</varname> geometry which is
+ used in the && operation is a 200 unit square box centered on
+ the original point - this is our "query box". The && operator
+ uses the index to quickly reduce the result set down to only those
+ geometries which have bounding boxes that overlap the "query box".
+ Assuming that our query box is much smaller than the extents of the
+ entire geometry table, this will drastically reduce the number of
+ distance calculations that need to be done.</para>
+
+ <note>
+ <title>Change in Behavior</title>
+
+ <para>As of PostGIS 1.3.0, most of the Geometry Relationship
+ Functions, with the notable exceptions of ST_Disjoint and ST_Relate,
+ include implicit bounding box overlap operators.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Examples of Spatial SQL</title>
+
+ <para>The examples in this section will make use of two tables, a table
+ of linear roads, and a table of polygonal municipality boundaries. The
+ table definitions for the <varname>bc_roads</varname> table is:</para>
+
+ <programlisting>Column | Type | Description
+------------+-------------------+-------------------
+gid | integer | Unique ID
+name | character varying | Road Name
+the_geom | geometry | Location Geometry (Linestring)</programlisting>
+
+ <para>The table definition for the <varname>bc_municipality</varname>
+ table is:</para>
+
+ <programlisting>Column | Type | Description
+-----------+-------------------+-------------------
+gid | integer | Unique ID
+code | integer | Unique ID
+name | character varying | City / Town Name
+the_geom | geometry | Location Geometry (Polygon)</programlisting>
+
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>What is the total length of all roads, expressed in
+ kilometers?</para>
+ </question>
+
+ <answer>
+ <para>You can answer this question with a very simple piece of
+ SQL:</para>
+
+ <programlisting>SELECT sum(ST_Length(the_geom))/1000 AS km_roads FROM bc_roads;
+
+km_roads
+------------------
+70842.1243039643
+(1 row)</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How large is the city of Prince George, in hectares?</para>
+ </question>
+
+ <answer>
+ <para>This query combines an attribute condition (on the
+ municipality name) with a spatial calculation (of the
+ area):</para>
+
+ <programlisting>SELECT
+ ST_Area(the_geom)/10000 AS hectares
+FROM bc_municipality
+WHERE name = 'PRINCE GEORGE';
+
+hectares
+------------------
+32657.9103824927
+(1 row)</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>What is the largest municipality in the province, by
+ area?</para>
+ </question>
+
+ <answer>
+ <para>This query brings a spatial measurement into the query
+ condition. There are several ways of approaching this problem, but
+ the most efficient is below:</para>
+
+ <programlisting>SELECT
+ name,
+ ST_Area(the_geom)/10000 AS hectares
+FROM
+ bc_municipality
+ORDER BY hectares DESC
+LIMIT 1;
+
+name | hectares
+---------------+-----------------
+TUMBLER RIDGE | 155020.02556131
+(1 row)</programlisting>
+
+ <para>Note that in order to answer this query we have to calculate
+ the area of every polygon. If we were doing this a lot it would
+ make sense to add an area column to the table that we could
+ separately index for performance. By ordering the results in a
+ descending direction, and them using the PostgreSQL "LIMIT"
+ command we can easily pick off the largest value without using an
+ aggregate function like max().</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>What is the length of roads fully contained within each
+ municipality?</para>
+ </question>
+
+ <answer>
+ <para>This is an example of a "spatial join", because we are
+ bringing together data from two tables (doing a join) but using a
+ spatial interaction condition ("contained") as the join condition
+ rather than the usual relational approach of joining on a common
+ key:</para>
+
+ <programlisting>SELECT
+ m.name,
+ sum(ST_Length(r.the_geom))/1000 as roads_km
+FROM
+ bc_roads AS r,
+ bc_municipality AS m
+WHERE
+ ST_Contains(m.the_geom,r.the_geom)
+GROUP BY m.name
+ORDER BY roads_km;
+
+name | roads_km
+----------------------------+------------------
+SURREY | 1539.47553551242
+VANCOUVER | 1450.33093486576
+LANGLEY DISTRICT | 833.793392535662
+BURNABY | 773.769091404338
+PRINCE GEORGE | 694.37554369147
+...</programlisting>
+
+ <para>This query takes a while, because every road in the table is
+ summarized into the final result (about 250K roads for our
+ particular example table). For smaller overlays (several thousand
+ records on several hundred) the response can be very fast.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>Create a new table with all the roads within the city of
+ Prince George.</para>
+ </question>
+
+ <answer>
+ <para>This is an example of an "overlay", which takes in two
+ tables and outputs a new table that consists of spatially clipped
+ or cut resultants. Unlike the "spatial join" demonstrated above,
+ this query actually creates new geometries. An overlay is like a
+ turbo-charged spatial join, and is useful for more exact analysis
+ work:</para>
+
+ <programlisting>CREATE TABLE pg_roads as
+SELECT
+ ST_Intersection(r.the_geom, m.the_geom) AS intersection_geom,
+ ST_Length(r.the_geom) AS rd_orig_length,
+ r.*
+FROM
+ bc_roads AS r,
+ bc_municipality AS m
+WHERE m.name = 'PRINCE GEORGE' AND ST_Intersects(r.the_geom, m.the_geom);</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>What is the length in kilometers of "Douglas St" in
+ Victoria?</para>
+ </question>
+
+ <answer>
+ <programlisting>SELECT
+ sum(ST_Length(r.the_geom))/1000 AS kilometers
+FROM
+ bc_roads r,
+ bc_municipality m
+WHERE r.name = 'Douglas St' AND m.name = 'VICTORIA'
+ AND ST_Contains(m.the_geom, r.the_geom) ;
+
+kilometers
+------------------
+4.89151904172838
+(1 row)</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>What is the largest municipality polygon that has a
+ hole?</para>
+ </question>
+
+ <answer>
+ <programlisting>SELECT gid, name, ST_Area(the_geom) AS area
+FROM bc_municipality
+WHERE ST_NRings(the_geom) > 1
+ORDER BY area DESC LIMIT 1;
+
+gid | name | area
+-----+--------------+------------------
+12 | SPALLUMCHEEN | 257374619.430216
+(1 row)</programlisting>
+ </answer>
+ </qandaentry>
+ </qandaset>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Using Mapserver</title>
+
+ <para>The Minnesota Mapserver is an internet web-mapping server which
+ conforms to the OpenGIS Web Mapping Server specification.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The Mapserver homepage is at <ulink
+ url="http://mapserver.gis.umn.edu">http://mapserver.gis.umn.edu</ulink>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The OpenGIS Web Map Specification is at <ulink
+ url="http://www.opengis.org/techno/specs/01-047r2.pdf">http://www.opengis.org/techno/specs/01-047r2.pdf</ulink>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <sect2>
+ <title>Basic Usage</title>
+
+ <para>To use PostGIS with Mapserver, you will need to know about how to
+ configure Mapserver, which is beyond the scope of this documentation.
+ This section will cover specific PostGIS issues and configuration
+ details.</para>
+
+ <para>To use PostGIS with Mapserver, you will need:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Version 0.6 or newer of PostGIS.</para>
+ </listitem>
+
+ <listitem>
+ <para>Version 3.5 or newer of Mapserver.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Mapserver accesses PostGIS/PostgreSQL data like any other
+ PostgreSQL client -- using <filename>libpq</filename>. This means that
+ Mapserver can be installed on any machine with network access to the
+ PostGIS server, as long as the system has the <filename>libpq</filename>
+ PostgreSQL client libraries.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Compile and install Mapserver, with whatever options you
+ desire, including the "--with-postgis" configuration option.</para>
+ </listitem>
+
+ <listitem>
+ <para>In your Mapserver map file, add a PostGIS layer. For
+ example:</para>
+
+ <programlisting>LAYER
+ CONNECTIONTYPE postgis
+ NAME "widehighways"
+ # Connect to a remote spatial database
+ CONNECTION "user=dbuser dbname=gisdatabase host=bigserver"
+ # Get the lines from the 'geom' column of the 'roads' table
+ DATA "geom from roads"
+ STATUS ON
+ TYPE LINE
+ # Of the lines in the extents, only render the wide highways
+ FILTER "type = 'highway' and numlanes >= 4"
+ CLASS
+ # Make the superhighways brighter and 2 pixels wide
+ EXPRESSION ([numlanes] >= 6)
+ COLOR 255 22 22
+ SYMBOL "solid"
+ SIZE 2
+ END
+ CLASS
+ # All the rest are darker and only 1 pixel wide
+ EXPRESSION ([numlanes] < 6)
+ COLOR 205 92 82
+ END
+END</programlisting>
+
+ <para>In the example above, the PostGIS-specific directives are as
+ follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>CONNECTIONTYPE</term>
+
+ <listitem>
+ <para>For PostGIS layers, this is always "postgis".</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>CONNECTION</term>
+
+ <listitem>
+ <para>The database connection is governed by the a 'connection
+ string' which is a standard set of keys and values like this
+ (with the default values in <>):</para>
+
+ <para>user=<username> password=<password>
+ dbname=<username> hostname=<server>
+ port=<5432></para>
+
+ <para>An empty connection string is still valid, and any of
+ the key/value pairs can be omitted. At a minimum you will
+ generally supply the database name and username to connect
+ with.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DATA</term>
+
+ <listitem>
+ <para>The form of this parameter is "<column> from
+ <tablename>" where the column is the spatial column to
+ be rendered to the map.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILTER</term>
+
+ <listitem>
+ <para>The filter must be a valid SQL string corresponding to
+ the logic normally following the "WHERE" keyword in a SQL
+ query. So, for example, to render only roads with 6 or more
+ lanes, use a filter of "num_lanes >= 6".</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+
+ <listitem>
+ <para>In your spatial database, ensure you have spatial (GiST)
+ indexes built for any the layers you will be drawing.</para>
+
+ <programlisting>CREATE INDEX [indexname] ON [tablename] USING GIST ( [geometrycolumn] );</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If you will be querying your layers using Mapserver you will
+ also need an "oid index".</para>
+
+ <para>Mapserver requires unique identifiers for each spatial record
+ when doing queries, and the PostGIS module of Mapserver uses the
+ PostgreSQL <varname>oid</varname> value to provide these unique
+ identifiers. A side-effect of this is that in order to do fast
+ random access of records during queries, an index on the
+ <varname>oid</varname> is needed.</para>
+
+ <para>To build an "oid index", use the following SQL:</para>
+
+ <programlisting>CREATE INDEX [indexname] ON [tablename] ( oid );</programlisting>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
+ <sect2>
+ <title>Frequently Asked Questions</title>
+
+ <qandaset>
+ <qandaentry>
+ <question>
+ <para>When I use an <varname>EXPRESSION</varname> in my map file,
+ the condition never returns as true, even though I know the values
+ exist in my table.</para>
+ </question>
+
+ <answer>
+ <para>Unlike shape files, PostGIS field names have to be
+ referenced in EXPRESSIONS using <emphasis>lower
+ case</emphasis>.</para>
+
+ <programlisting>EXPRESSION ([numlanes] >= 6)</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>The FILTER I use for my Shape files is not working for my
+ PostGIS table of the same data.</para>
+ </question>
+
+ <answer>
+ <para>Unlike shape files, filters for PostGIS layers use SQL
+ syntax (they are appended to the SQL statement the PostGIS
+ connector generates for drawing layers in Mapserver).</para>
+
+ <programlisting>FILTER "type = 'highway' and numlanes >= 4"</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>My PostGIS layer draws much slower than my Shape file layer,
+ is this normal?</para>
+ </question>
+
+ <answer>
+ <para>In general, expect PostGIS layers to be 10% slower than
+ equivalent Shape files layers, due to the extra overhead involved
+ in database connections, data transformations and data transit
+ between the database and Mapserver.</para>
+
+ <para>If you are finding substantial draw performance problems, it
+ is likely that you have not build a spatial index on your
+ table.</para>
+
+ <programlisting>postgis# CREATE INDEX geotable_gix ON geotable USING GIST ( geocolumn );
+postgis# SELECT update_geometry_stats(); -- For PGSQL < 8.0
+postgis# VACUUM ANALYZE; -- For PGSQL >= 8.0</programlisting>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>My PostGIS layer draws fine, but queries are really slow.
+ What is wrong?</para>
+ </question>
+
+ <answer>
+ <para>For queries to be fast, you must have a unique key for your
+ spatial table and you must have an index on that unique
+ key.</para>
+
+ <para>You can specify what unique key for mapserver to use with
+ the <varname>USING UNIQUE</varname> clause in your
+ <varname>DATA</varname> line:</para>
+
+ <programlisting>DATA "the_geom FROM geotable USING UNIQUE gid"</programlisting>
+
+ <para>If your table does not have an explicit unique column, you
+ can "fake" a unique column by using the PostgreSQL row "oid" for
+ your unique column. "oid" is the default unique column if you do
+ not declare one, so enhancing your query speed is a matter of
+ building an index on your spatial table oid value.</para>
+
+ <programlisting>postgis# CREATE INDEX geotable_oid_idx ON geotable (oid);</programlisting>
+ </answer>
+ </qandaentry>
+ </qandaset>
+ </sect2>
+
+ <sect2>
+ <title>Advanced Usage</title>
+
+ <para>The <varname>USING</varname> pseudo-SQL clause is used to add some
+ information to help mapserver understand the results of more complex
+ queries. More specifically, when either a view or a subselect is used as
+ the source table (the thing to the right of "FROM" in a
+ <varname>DATA</varname> definition) it is more difficult for mapserver
+ to automatically determine a unique identifier for each row and also the
+ SRID for the table. The <varname>USING</varname> clause can provide
+ mapserver with these two pieces of information as follows:</para>
+
+ <programlisting>DATA "the_geom FROM (
+ SELECT
+ table1.the_geom AS the_geom,
+ table1.oid AS oid,
+ table2.data AS data
+ FROM table1
+ LEFT JOIN table2
+ ON table1.id = table2.id
+) AS new_table USING UNIQUE oid USING SRID=-1"</programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term>USING UNIQUE <uniqueid></term>
+
+ <listitem>
+ <para>Mapserver requires a unique id for each row in order to
+ identify the row when doing map queries. Normally, it would use
+ the oid as the unique identifier, but views and subselects don't
+ automatically have an oid column. If you want to use Mapserver's
+ query functionality, you need to add a unique column to your view
+ or subselect, and declare it with <varname>USING UNIQUE</varname>.
+ For example, you could explicitly select one of the table's oid
+ values for this purpose, or any other column which is guaranteed
+ to be unique for the result set.</para>
+
+ <para>The <varname>USING</varname> statement can also be useful
+ even for simple <varname>DATA</varname> statements, if you are
+ doing map queries. It was previously recommended to add an index
+ on the oid column of tables used in query-able layers, in order to
+ speed up the performance of map queries. However, with the
+ <varname>USING</varname> clause, it is possible to tell mapserver
+ to use your table's primary key as the identifier for map queries,
+ and then it is no longer necessary to have an additional
+ index.</para>
+
+ <note>
+ <para>"Querying a Map" is the action of clicking on a map to ask
+ for information about the map features in that location. Don't
+ confuse "map queries" with the SQL query in a
+ <varname>DATA</varname> definition.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>USING SRID=<srid></term>
+
+ <listitem>
+ <para>PostGIS needs to know which spatial referencing system is
+ being used by the geometries in order to return the correct data
+ back to mapserver. Normally it is possible to find this
+ information in the "geometry_columns" table in the PostGIS
+ database, however, this is not possible for tables which are
+ created on the fly such as subselects and views. So the
+ <varname>USING SRID=</varname> option allows the correct SRID to
+ be specified in the <varname>DATA</varname> definition.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <warning>
+ <para>The parser for Mapserver PostGIS layers is fairly primitive, and
+ is case sensitive in a few areas. Be careful to ensure that all SQL
+ keywords and all your <varname>USING</varname> clauses are in upper
+ case, and that your <varname>USING UNIQUE</varname> clause precedes
+ your <varname>USING SRID</varname> clause.</para>
+ </warning>
+ </sect2>
+
+ <sect2>
+ <title>Examples</title>
+
+ <para>Lets start with a simple example and work our way up. Consider the
+ following Mapserver layer definition:</para>
+
+ <programlisting>LAYER
+ CONNECTIONTYPE postgis
+ NAME "roads"
+ CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
+ DATA "the_geom FROM roads"
+ STATUS ON
+ TYPE LINE
+ CLASS
+ COLOR 0 0 0
+ END
+END</programlisting>
+
+ <para>This layer will display all the road geometries in the roads table
+ as black lines.</para>
+
+ <para>Now lets say we want to show only the highways until we get zoomed
+ in to at least a 1:100000 scale - the next two layers will achieve this
+ effect:</para>
+
+ <programlisting>LAYER
+ CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
+ DATA "the_geom FROM roads"
+ MINSCALE 100000
+ STATUS ON
+ TYPE LINE
+ FILTER "road_type = 'highway'"
+ CLASS
+ COLOR 0 0 0
+ END
+END
+LAYER
+ CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
+ DATA "the_geom FROM roads"
+ MAXSCALE 100000
+ STATUS ON
+ TYPE LINE
+ CLASSITEM road_type
+ CLASS
+ EXPRESSION "highway"
+ SIZE 2
+ COLOR 255 0 0
+ END
+ CLASS
+ COLOR 0 0 0
+ END
+END</programlisting>
+
+ <para>The first layer is used when the scale is greater than 1:100000,
+ and displays only the roads of type "highway" as black lines. The
+ <varname>FILTER</varname> option causes only roads of type "highway" to
+ be displayed.</para>
+
+ <para>The second layer is used when the scale is less than 1:100000, and
+ will display highways as double-thick red lines, and other roads as
+ regular black lines.</para>
+
+ <para>So, we have done a couple of interesting things using only
+ mapserver functionality, but our <varname>DATA</varname> SQL statement
+ has remained simple. Suppose that the name of the road is stored in
+ another table (for whatever reason) and we need to do a join to get it
+ and label our roads.</para>
+
+ <programlisting>LAYER
+ CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
+ DATA "the_geom FROM (SELECT roads.oid AS oid, roads.the_geom AS the_geom,
+ road_names.name as name FROM roads LEFT JOIN road_names ON
+ roads.road_name_id = road_names.road_name_id)
+ AS named_roads USING UNIQUE oid USING SRID=-1"
+ MAXSCALE 20000
+ STATUS ON
+ TYPE ANNOTATION
+ LABELITEM name
+ CLASS
+ LABEL
+ ANGLE auto
+ SIZE 8
+ COLOR 0 192 0
+ TYPE truetype
+ FONT arial
+ ENDl
+ END
+END</programlisting>
+
+ <para>This annotation layer adds green labels to all the roads when the
+ scale gets down to 1:20000 or less. It also demonstrates how to use an
+ SQL join in a <varname>DATA</varname> definition.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Java Clients (JDBC)</title>
+
+ <para>Java clients can access PostGIS "geometry" objects in the PostgreSQL
+ database either directly as text representations or using the JDBC
+ extension objects bundled with PostGIS. In order to use the extension
+ objects, the "postgis.jar" file must be in your CLASSPATH along with the
+ "postgresql.jar" JDBC driver package.</para>
+
+ <programlisting>import java.sql.*;
+import java.util.*;
+import java.lang.*;
+import org.postgis.*;
+
+public class JavaGIS {
+
+public static void main(String[] args) {
+
+ java.sql.Connection conn;
+
+ try {
+ /*
+ * Load the JDBC driver and establish a connection.
+ */
+ Class.forName("org.postgresql.Driver");
+ String url = "jdbc:postgresql://localhost:5432/database";
+ conn = DriverManager.getConnection(url, "postgres", "");
+ /*
+ * Add the geometry types to the connection. Note that you
+ * must cast the connection to the pgsql-specific connection
+ * implementation before calling the addDataType() method.
+ */
+ ((org.postgresql.Connection)conn).addDataType("geometry","org.postgis.PGgeometry")
+;
+ ((org.postgresql.Connection)conn).addDataType("box3d","org.postgis.PGbox3d");
+ /*
+ * Create a statement and execute a select query.
+ */
+ Statement s = conn.createStatement();
+ ResultSet r = s.executeQuery("select AsText(geom) as geom,id from geomtable");
+ while( r.next() ) {
+ /*
+ * Retrieve the geometry as an object then cast it to the geometry type.
+ * Print things out.
+ */
+ PGgeometry geom = (PGgeometry)r.getObject(1);
+ int id = r.getInt(2);
+ System.out.println("Row " + id + ":");
+ System.out.println(geom.toString());
+ }
+ s.close();
+ conn.close();
+ }
+catch( Exception e ) {
+ e.printStackTrace();
+ }
+}
+}</programlisting>
+
+ <para>The "PGgeometry" object is a wrapper object which contains a
+ specific topological geometry object (subclasses of the abstract class
+ "Geometry") depending on the type: Point, LineString, Polygon, MultiPoint,
+ MultiLineString, MultiPolygon.</para>
+
+ <programlisting>PGgeometry geom = (PGgeometry)r.getObject(1);
+if( geom.getType() = Geometry.POLYGON ) {
+ Polygon pl = (Polygon)geom.getGeometry();
+ for( int r = 0; r < pl.numRings(); r++) {
+ LinearRing rng = pl.getRing(r);
+ System.out.println("Ring: " + r);
+ for( int p = 0; p < rng.numPoints(); p++ ) {
+ Point pt = rng.getPoint(p);
+ System.out.println("Point: " + p);
+ System.out.println(pt.toString());
+ }
+ }
+}</programlisting>
+
+ <para>The JavaDoc for the extension objects provides a reference for the
+ various data accessor functions in the geometric objects.</para>
+ </sect1>
+
+ <sect1>
+ <title>C Clients (libpq)</title>
+
+ <para>...</para>
+
+ <sect2>
+ <title>Text Cursors</title>
+
+ <para>...</para>
+ </sect2>
+
+ <sect2>
+ <title>Binary Cursors</title>
+
+ <para>...</para>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
projects / postgis / commitdiff