-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
-<book>
- <title>PostGIS Manual</title>
- <bookinfo>
- <editor>
- <firstname>Paul</firstname>
- <surname>Ramsey</surname>
- <affiliation>
- <orgname><ulink url="http://www.refractions.net">Refractions Research Inc</ulink></orgname>
- <address>
- <street>400 - 1207 Douglas Street</street>
- <city>Victoria</city>
- <state>British Columbia</state>
- <country>Canada</country>
- <email>pramsey@refractions.net</email>
- </address>
- </affiliation>
- </editor>
- <abstract>
- <para>PostGIS is an extension to the PostgreSQL object-relational database system
- which allows GIS (Geographic Information Systems) objects to be stored in the
- database. PostGIS includes support for GiST-based R-Tree spatial indexes, and
- functions for basic analysis of GIS objects.
- </para>
- </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>
- <title>Credits</title>
- <variablelist>
- <varlistentry>
- <term>Dave Blasby <dblasby@refractions.net></term>
- <listitem>
- <para>The principal developer of PostGIS. Dave maintains the server
- side objects and index support, the server side analytical
- functions, and the Mapserver connectivity.
- </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>Maintains the JDBC objects and keeps track of the
- documentation and packaging.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Jeff Lounsbury <jeffloun@refractions.net></term>
- <listitem>
- <para>Maintains the Shape loader/dumper.</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 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 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/techno/specs/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 configured and built PostgreSQL source code tree.
- PostGIS uses definitions from the PostgreSQL configure/build process
- to conform to the particular platform you are building on.
- PostgreSQL is available from
- <ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>.
- </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>(Optional) 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>
- </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> a full copy of the
- PostgreSQL source tree 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.1.0 to 7.4.x.
- 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>
- <para><emphasis>NOTE</emphasis>: if you plan to use GEOS
- functionality you might need to 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 that.
- </para>
- </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 in the "contrib" directory of
- the PostgreSQL source tree.
- </para>
- <programlisting># cd [postgresql source tree]/contrib
-# gzip -d -c postgis-@@LAST_RELEASE_VERSION@@.tar.gz | tar xvf -</programlisting>
- </listitem>
- <listitem>
- <para>Once your PostgreSQL installation is up-to-date, enter the
- "postgis" directory, and edit the <filename>Makefile</filename>.
- </para>
- <itemizedlist>
- <listitem>
- <para>If you are compiling PostGIS 0.7.2 or earlier
- against PostgreSQL 7.2.x, you must set the
- <varname>USE_PG72</varname> variable to
- <emphasis>1</emphasis>. This is done automatically by
- newer version of postgis.
- </para>
- </listitem>
- <listitem>
- <para>If want support for coordinate reprojection you must
- have the Proj4 library installed, set the
- <varname>USE_PROJ</varname> variable to <emphasis>1</emphasis>,
- and eventually adjust <varname>PROJ_DIR</varname> to point
- to your Proj4 installation directory.
- </para>
- </listitem>
- <listitem>
- <para>If want to use GEOS functionalities you must
- have the GEOS library installed, set the
- <varname>USE_GEOS</varname> variable to <emphasis>1</emphasis>,
- and eventually adjust <varname>GEOS_DIR</varname> to point to
- your GEOS installation directory.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>Run the compile and install commands.</para>
- <programlisting># make
+<?xml version="1.0" encoding="UTF-8"?>
+<book>
+ <title>PostGIS Manual</title>
+
+ <bookinfo>
+ <editor>
+ <firstname>Paul</firstname>
+
+ <surname>Ramsey</surname>
+
+ <affiliation>
+ <orgname><ulink url="http://www.refractions.net">Refractions Research
+ Inc</ulink></orgname>
+
+ <address>
+ <street>400 - 1207 Douglas Street</street>
+ <city>Victoria</city>
+ <state>British Columbia</state>
+ <country>Canada</country>
+ <email>pramsey@refractions.net</email>
+ </address>
+ </affiliation>
+ </editor>
+
+ <abstract>
+ <para>PostGIS is an extension to the PostgreSQL object-relational
+ database system which allows GIS (Geographic Information Systems)
+ objects to be stored in the database. PostGIS includes support for
+ GiST-based R-Tree spatial indexes, and functions for basic analysis of
+ GIS objects.</para>
+ </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>
+ <title>Credits</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>Dave Blasby <dblasby@refractions.net></term>
+
+ <listitem>
+ <para>The principal developer of PostGIS. Dave maintains the
+ server side objects and index support, the server side analytical
+ functions, and the Mapserver connectivity.</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>Maintains the JDBC objects and keeps track of the
+ documentation and packaging.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Jeff Lounsbury <jeffloun@refractions.net></term>
+
+ <listitem>
+ <para>Maintains the Shape loader/dumper.</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 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 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/techno/specs/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 configured and built PostgreSQL source code tree.
+ PostGIS uses definitions from the PostgreSQL configure/build process
+ to conform to the particular platform you are building on.
+ PostgreSQL is available from <ulink
+ url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</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>(Optional) 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>
+ </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> a full copy of the PostgreSQL source tree
+ 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.1.0 to 7.4.x. 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>
+
+ <para><emphasis>NOTE</emphasis>: if you plan to use GEOS
+ functionality you might need to 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 that.</para>
+ </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 in the "contrib" directory of the
+ PostgreSQL source tree.</para>
+
+ <programlisting># cd [postgresql source tree]/contrib
+# gzip -d -c postgis-@@LAST_RELEASE_VERSION@@.tar.gz | tar xvf -</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Once your PostgreSQL installation is up-to-date, enter the
+ "postgis" directory, and edit the
+ <filename>Makefile</filename>.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If you are compiling PostGIS 0.7.2 or earlier against
+ PostgreSQL 7.2.x, you must set the <varname>USE_PG72</varname>
+ variable to <emphasis>1</emphasis>. This is done automatically
+ by newer version of postgis.</para>
+ </listitem>
+
+ <listitem>
+ <para>If want support for coordinate reprojection you must have
+ the Proj4 library installed, set the <varname>USE_PROJ</varname>
+ variable to <emphasis>1</emphasis>, and eventually adjust
+ <varname>PROJ_DIR</varname> to point to your Proj4 installation
+ directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>If want to use GEOS functionalities you must have the GEOS
+ library installed, set the <varname>USE_GEOS</varname> variable
+ to <emphasis>1</emphasis>, and eventually adjust
+ <varname>GEOS_DIR</varname> to point to your GEOS installation
+ directory.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Run the compile and install commands.</para>
+
+ <programlisting># make
# make install</programlisting>
- <para>All files are installed relative to the PostgreSQL install
- directory, <filename>[prefix]</filename>.
- </para>
- <itemizedlist>
- <listitem>
- <para>Libraries are installed
- <filename>[prefix]/lib/contrib</filename>.
- </para>
- </listitem>
- <listitem>
- <para>Important support files such as
- <filename>postgis.sql</filename> are installed in
- <filename>[prefix]/share/contrib</filename>.
- </para>
- </listitem>
- <listitem>
- <para>Loader and dumber binaries are installed in
- <filename>[prefix]/bin</filename>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>PostGIS requires the PL/pgSQL procedural language extension.
- Before loading the <filename>postgis.sql</filename> file,
- you must first enable PL/pgSQL. You should use the
- <filename>createlang</filename> command. The PostgreSQL 7.1
- 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>postgis.sql</filename>
- definitions file.
- </para>
- <programlisting># psql -d [yourdatabase] -f postgis.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>
- <title>Upgrading</title>
- <para>Upgrading PostGIS can be tricky, because the underlying C libraries
- which support the object types and geometries may have changed between
- versions. To avoid problems when upgrading, you will have to dump all
- the tables in your database, destroy the database, create a new one,
- execute the new <filename>postgis.sql</filename> file, then upload your
- database dump:
- </para>
- <programlisting># pg_dump -t "*" -f dumpfile.sql yourdatabase
+
+ <para>All files are installed relative to the PostgreSQL install
+ directory, <filename>[prefix]</filename>.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Libraries are installed
+ <filename>[prefix]/lib/contrib</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Important support files such as
+ <filename>postgis.sql</filename> are installed in
+ <filename>[prefix]/share/contrib</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Loader and dumber binaries are installed in
+ <filename>[prefix]/bin</filename>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>PostGIS requires the PL/pgSQL procedural language extension.
+ Before loading the <filename>postgis.sql</filename> file, you must
+ first enable PL/pgSQL. You should use the
+ <filename>createlang</filename> command. The PostgreSQL 7.1
+ 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>postgis.sql</filename> definitions
+ file.</para>
+
+ <programlisting># psql -d [yourdatabase] -f postgis.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>
+ <title>Upgrading</title>
+
+ <para>Upgrading PostGIS can be tricky, because the underlying C
+ libraries which support the object types and geometries may have
+ changed between versions. To avoid problems when upgrading, you will
+ have to dump all the tables in your database, destroy the database,
+ create a new one, execute the new <filename>postgis.sql</filename>
+ file, then upload your database dump:</para>
+
+ <programlisting># pg_dump -t "*" -f dumpfile.sql yourdatabase
# dropdb yourdatabase
# createdb yourdatabase
# createlang plpgsql yourdatabse
# psql -f postgis.sql -d yourdatabase
# psql -f dumpfile.sql -d yourdatabase
# vacuumdb -z yourdatabase</programlisting>
- <note>
- <para>When upgrading from version 0.5 to 0.6+, all your geometries
- will be created with an SRID of -1. To create valid OpenGIS
- geometries, you will have to create a valid SRID in the
- SPATIAL_REF_SYS table, and then update your geometries to
- reference the SRID with the following SQL (with the appropriate
- substitutions:
- </para>
- <programlisting>UPDATE TABLE <table> SET <geocolumn> = SetSRID(<geocolumn>,<SRID>);</programlisting>
- </note>
- </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 <filename>PGSQL_SRC</filename>environment
- variable to the path to the PostgreSQL source directory. This
- will allow you to compile PostGIS, but the
- <filename>make install</filename> 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.1 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) distrubution has
- already installed PostgreSQL, or you have otherwise installed
- PostgreSQL before and forgotten about it. PostGIS will only
- work with PostgreSQL 7.1 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>
- </listitem>
- </orderedlist>
- <para>Also check that you have made any necessary changes to the top
- of the Makefile. This includes:
- </para>
- <orderedlist>
- <listitem>
- <para>Changing the <filename>USE_PG72=0</filename> line to
- <filename>USE_PG72=1</filename> if you are using PostgreSQL
- 7.2 or newer. If this line is incorrect, it will result in
- a large number of errors being generated either when compiling,
- or when executing the sql statements in the postgis.sql file.
- </para>
- </listitem>
- <listitem>
- <para>If you want to be able to do coordinate
- reprojections, you must install the Proj.4 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.
- </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.
- </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
+
+ <note>
+ <para>When upgrading from version 0.5 to 0.6+, all your geometries
+ will be created with an SRID of -1. To create valid OpenGIS
+ geometries, you will have to create a valid SRID in the
+ SPATIAL_REF_SYS table, and then update your geometries to reference
+ the SRID with the following SQL (with the appropriate
+ substitutions:</para>
+
+ <programlisting>UPDATE TABLE <table> SET <geocolumn> = SetSRID(<geocolumn>,<SRID>);</programlisting>
+ </note>
+ </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
+ <filename>PGSQL_SRC</filename>environment variable to the path to
+ the PostgreSQL source directory. This will allow you to compile
+ PostGIS, but the <filename>make install</filename> 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.1 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) distrubution has already
+ installed PostgreSQL, or you have otherwise installed PostgreSQL
+ before and forgotten about it. PostGIS will only work with
+ PostgreSQL 7.1 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>
+ </listitem>
+ </orderedlist>
+
+ <para>Also check that you have made any necessary changes to the top
+ of the Makefile. This includes:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Changing the <filename>USE_PG72=0</filename> line to
+ <filename>USE_PG72=1</filename> if you are using PostgreSQL 7.2 or
+ newer. If this line is incorrect, it will result in a large number
+ of errors being generated either when compiling, or when executing
+ the sql statements in the postgis.sql file.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you want to be able to do coordinate reprojections, you
+ must install the Proj.4 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.</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.</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 into ESRI shape files.
- </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 3d 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) );
+
+ <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 into ESRI shape files.</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 3d 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('dbname','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', GeometryFromText('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
+
+ <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', GeometryFromText('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 | 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>There are a number of spatial operators available to
- PostgreSQL, and several of them have been implemented by PostGIS
- in order to provide indexing support.
- </para>
- <para>In order to do a spatial query with index support, you must
- use the "overlap operator" (&&) which uses the following
- important simplifying assumption: <emphasis>all features shall be
- represented by their bounding boxes</emphasis>.
- </para>
- <para>We recognize that using bounding boxes to proxy for features is
- a limiting assumption, but it is an important one in providing
- spatial indexing capabilities. Commercial spatial databases use
- the same assumption -- bounding boxes are important to most
- spatial indexing schemes.
- </para>
- <para>The most important spatial operator from a user's perspective
- is the "&&" overlap operator, which tests whether one
- feature's bounding box overlaps that of another. An example of a
- spatial query using && is:
- </para>
- <programlisting>SELECT id,name FROM GTEST WHERE GEOM && 'BOX3D(3 4,4 5)'::box3d</programlisting>
- <para>Note that the bounding box used for querying must be
- explicitly declared as a <varname>box3d</varname> using the
- "::box3d" casting operation.
- </para>
- </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 in 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]
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question>
+ <para>How do I construct a spatial query?</para>
+ </question>
+
+ <answer>
+ <para>There are a number of spatial operators available to
+ PostgreSQL, and several of them have been implemented by PostGIS in
+ order to provide indexing support.</para>
+
+ <para>In order to do a spatial query with index support, you must
+ use the "overlap operator" (&&) which uses the following
+ important simplifying assumption: <emphasis>all features shall be
+ represented by their bounding boxes</emphasis>.</para>
+
+ <para>We recognize that using bounding boxes to proxy for features
+ is a limiting assumption, but it is an important one in providing
+ spatial indexing capabilities. Commercial spatial databases use the
+ same assumption -- bounding boxes are important to most spatial
+ indexing schemes.</para>
+
+ <para>The most important spatial operator from a user's perspective
+ is the "&&" overlap operator, which tests whether one
+ feature's bounding box overlaps that of another. An example of a
+ spatial query using && is:</para>
+
+ <programlisting>SELECT id,name FROM GTEST WHERE GEOM && 'BOX3D(3 4,4 5)'::box3d</programlisting>
+
+ <para>Note that the bounding box used for querying must be
+ explicitly declared as a <varname>box3d</varname> using the
+ "::box3d" casting operation.</para>
+ </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 in 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] gist_geometry_ops);</programlisting>
- <para>The "USING GIST" option tells the server to use a GiST
- (Generalized Search Tree) index. The reference to
- "gist_geometry_ops" tells the server to use a particular set
- of comparison operators for building the index: the
- "gist_geometry_ops" are part of the PostGIS extension.
- <note>
- <para>For PostgreSQL version 7.1.x, you can specifically
- request a "lossy" index by appending WITH (ISLOSSY) to
- the index creation command. For PostgreSQL 7.2.x and
- above all 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>
- </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>For example, to find all objects with 100 meters of
- POINT(1000 1000) the following query would work well:
- </para>
- <programlisting>SELECT *
+
+ <para>The "USING GIST" option tells the server to use a GiST
+ (Generalized Search Tree) index. The reference to
+ "gist_geometry_ops" tells the server to use a particular set of
+ comparison operators for building the index: the "gist_geometry_ops"
+ are part of the PostGIS extension. <note>
+ <para>For PostgreSQL version 7.1.x, you can specifically request
+ a "lossy" index by appending WITH (ISLOSSY) to the index
+ creation command. For PostgreSQL 7.2.x and above all 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>
+ </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>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
GEOM && GeometryFromText('BOX3D(900 900,1100 1100)',-1)
AND
Distance(GeometryFromText('POINT(1000 1000)',-1),GEOM) < 100;</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 Transform(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 the "Simple Features"
- defined by the OpenGIS Consortium (OGC). Note that PostGIS currently supports
- the features and the representation APIs, but not the various comparison and
- convolution operators given in the OGC "Simple Features for SQL"
- specification.</para>
- <para>Examples of the text representations of the features are as
- follows:
- </para>
- <itemizedlist>
- <listitem>
- <para>POINT(0 0 0)</para>
- </listitem>
- <listitem>
- <para>LINESTRING(0 0,1 1,1 2)</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>MULTIPOINT(0 0 0,1 2 1)</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>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>GEOMETRYCOLLECTION(POINT(2 3 9),LINESTRING((2 3 4,3 4 5)))</para>
- </listitem>
- </itemizedlist>
- <para>Note that in the examples above there are features with both
- 2-dimensional and 3-dimensional coordinates. PostGIS supports both 2d and 3d
- coordinates -- if you describe a feature with 2D coordinates when you insert
- it, the database will return that feature to you with 2D coordinates when you
- extract it. See the sections on the <link linkend="force_2d">force_2d()</link>
- and <link linkend="force_3d">force_3d()</link> functions for information on
- converting features to a particular coordinate dimension representation.
- </para>
- <sect2>
- <title>Standard versus Canonical Forms</title>
- <para>The OpenGIS specification defines two standard ways of expressing
- spatial objects: the Well-Known Text (WKT) form (shown in the previous
- section) and the Well-Known Binary (WKB) form. Both WKT and WKB
- include information about the type of the object and the coordinates
- which form the object.
- </para>
- <para>However, the OpenGIS specification also requires that the
- internal storage format of spatial objects include a spatial
- referencing system identifier (SRID). The SRID is required when
- creating spatial objects for insertion into the database. For
- example, a valid insert statement to create and insert a spatial
- object would be:
- </para>
- <programlisting>INSERT INTO SPATIALTABLE ( THE_GEOM, THE_NAME )
+ </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 Transform(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 the "Simple Features"
+ defined by the OpenGIS Consortium (OGC). Note that PostGIS currently
+ supports the features and the representation APIs, but not the various
+ comparison and convolution operators given in the OGC "Simple Features
+ for SQL" specification.</para>
+
+ <para>Examples of the text representations of the features are as
+ follows:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>POINT(0 0 0)</para>
+ </listitem>
+
+ <listitem>
+ <para>LINESTRING(0 0,1 1,1 2)</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>MULTIPOINT(0 0 0,1 2 1)</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>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>GEOMETRYCOLLECTION(POINT(2 3 9),LINESTRING((2 3 4,3 4
+ 5)))</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that in the examples above there are features with both
+ 2-dimensional and 3-dimensional coordinates. PostGIS supports both 2d
+ and 3d coordinates -- if you describe a feature with 2D coordinates when
+ you insert it, the database will return that feature to you with 2D
+ coordinates when you extract it. See the sections on the <link
+ linkend="force_2d">force_2d()</link> and <link
+ linkend="force_3d">force_3d()</link> functions for information on
+ converting features to a particular coordinate dimension
+ representation.</para>
+
+ <sect2>
+ <title>Standard versus Canonical Forms</title>
+
+ <para>The OpenGIS specification defines two standard ways of
+ expressing spatial objects: the Well-Known Text (WKT) form (shown in
+ the previous section) and the Well-Known Binary (WKB) form. Both WKT
+ and WKB include information about the type of the object and the
+ coordinates which form the object.</para>
+
+ <para>However, the OpenGIS specification also requires that the
+ internal storage format of spatial objects include a spatial
+ referencing system identifier (SRID). The SRID is required when
+ creating spatial objects for insertion into the database. For example,
+ a valid insert statement to create and insert a spatial object would
+ be:</para>
+
+ <programlisting>INSERT INTO SPATIALTABLE ( THE_GEOM, THE_NAME )
VALUES (
GeometryFromText('POINT(-126.4 45.32)', 312),
'A Place'
- )</programlisting>
- <para>Note that the "GeometryFromText" function requires an SRID
- number.
- </para>
- <para>The "canonical form" of the spatial objects in PostgreSQL is a
- text representation which includes all the information necessary
- to construct the object. Unlike the OpenGIS standard forms, it
- includes the type, coordinate, and SRID information. The canonical
- form is the default form returned from a SELECT query. The example
- below shows the difference between the OGC standard and PostGIS
- canonical forms:
- </para>
- <programlisting>db=> SELECT AsText(geom) AS OGCGeom FROM thetable;
+ )</programlisting>
+
+ <para>Note that the "GeometryFromText" function requires an SRID
+ number.</para>
+
+ <para>The "canonical form" of the spatial objects in PostgreSQL is a
+ text representation which includes all the information necessary to
+ construct the object. Unlike the OpenGIS standard forms, it includes
+ the type, coordinate, and SRID information. The canonical form is the
+ default form returned from a SELECT query. The example below shows the
+ difference between the OGC standard and PostGIS canonical
+ forms:</para>
+
+ <programlisting>db=> SELECT AsText(geom) AS OGCGeom FROM thetable;
OGCGeom
-------------------------------------------------
LINESTRING(-123.741378393049 48.9124018962261,-123.741587115639 48.9123981907507)
-------------------------------------------------
SRID=123;LINESTRING(-123.741378393049 48.9124018962261,-123.741587115639 48.9123981907507)
(1 row)</programlisting>
- </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: SPATIAL_REF_SYS and
- GEOMETRY_COLUMNS. The SPATIAL_REF_SYS 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 SPATIAL_REF_SYS table definition is as follows:</para>
- <programlisting>CREATE TABLE SPATIAL_REF_SYS (
+ </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: SPATIAL_REF_SYS and
+ GEOMETRY_COLUMNS. The SPATIAL_REF_SYS 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 SPATIAL_REF_SYS 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 SPATIAL_REF_SYS columns are as follows:</para>
- <variablelist>
- <varlistentry>
- <term>SRID</term>
- <listitem>
- <para>An integer value that uniquely identifies the Spatial
- Referencing System 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 AUTH_NAME.
- </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 AUTH_NAME. 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",
+)</programlisting>
+
+ <para>The SPATIAL_REF_SYS columns are as follows:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SRID</term>
+
+ <listitem>
+ <para>An integer value that uniquely identifies the Spatial
+ Referencing System 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 AUTH_NAME.</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 AUTH_NAME. 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",
+ DATUM["North_American_Datum_1983",
SPHEROID["GRS 1980",6378137,298.257222101]
- ],
+ ],
PRIMEM["Greenwich",0],
UNIT["degree",0.0174532925199433]
],
- PROJECTION["Transverse_Mercator"],
+ PROJECTION["Transverse_Mercator"],
PARAMETER["latitude_of_origin",0],
- PARAMETER["central_meridian",-123],
+ PARAMETER["central_meridian",-123],
PARAMETER["scale_factor",0.9996],
- PARAMETER["false_easting",500000],
+ 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>.
- </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 (
+ 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>.</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 VARCHAR(256) NOT NULL,
F_TABLE_SCHEMA VARCHAR(256) NOT NULL,
F_TABLE_NAME VARCHAR(256) NOT NULL,
F_GEOMETRY_COLUMN VARCHAR(256) NOT NULL,
- COORD_DIMENSION INTEGER 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
- database name is used.
- </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 or 3 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
- SPATIAL_REF_SYS.
- </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, MULTPOINT, MULTILINESTRING, MULTIPOLYGON,
- GEOMETRYCOLLECTION. 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: CREATE TABLE ROADS_GEOM ( ID int4, NAME
- varchar(25) )
- </para>
- </listitem>
- <listitem>
- <para>Add a spatial column to the table using the OpenGIS
- "AddGeometryColumn" function. The syntax is:
- AddGeometryColumn(<db_name>, <table_name>,
- <column_name>, <srid>, <type>,
- <dimension>).
- </para>
- <para>For example: SELECT AddGeometryColumn('roads_db',
- 'roads_geom', 'geom', 423, 'LINESTRING', 2)
- </para>
- </listitem>
- </itemizedlist>
- <para>Here is an example of SQL used to create a table and add a
- spatial column (assuming the db is 'parks_db' and that an SRID of 128 exists
- already):
- </para>
- <programlisting>CREATE TABLE PARKS ( PARK_ID int4, PARK_NAME varchar(128), PARK_DATE date, PARK_TYPE varchar(2) );
-SELECT AddGeometryColumn('parks_db', '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 int4, ROAD_NAME varchar(128) );
-SELECT AddGeometryColumn( 'roads_db', 'roads', 'roads_geom', -1, 'GEOMETRY', 3 );</programlisting>
- </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;
+)</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 database name is
+ used.</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 or 3 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 SPATIAL_REF_SYS.</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,
+ MULTPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION.
+ 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: CREATE TABLE ROADS_GEOM ( ID int4, NAME
+ varchar(25) )</para>
+ </listitem>
+
+ <listitem>
+ <para>Add a spatial column to the table using the OpenGIS
+ "AddGeometryColumn" function. The syntax is:
+ AddGeometryColumn(<db_name>, <table_name>,
+ <column_name>, <srid>, <type>,
+ <dimension>).</para>
+
+ <para>For example: SELECT AddGeometryColumn('roads_db',
+ 'roads_geom', 'geom', 423, 'LINESTRING', 2)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Here is an example of SQL used to create a table and add a
+ spatial column (assuming the db is 'parks_db' and that an SRID of 128
+ exists already):</para>
+
+ <programlisting>CREATE TABLE PARKS ( PARK_ID int4, PARK_NAME varchar(128), PARK_DATE date, PARK_TYPE varchar(2) );
+SELECT AddGeometryColumn('parks_db', '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 int4, ROAD_NAME varchar(128) );
+SELECT AddGeometryColumn( 'roads_db', 'roads', 'roads_geom', -1, 'GEOMETRY', 3 );</programlisting>
+ </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_GEOM (ID,GEOM,NAME ) VALUES (1,GeometryFromText('LINESTRING(191232 243118,191108 243242)',-1),'Jeff Rd');
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (2,GeometryFromText('LINESTRING(189141 244158,189265 244817)',-1),'Geordie Rd');
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (3,GeometryFromText('LINESTRING(192783 228138,192612 229814)',-1),'Paul St');
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (4,GeometryFromText('LINESTRING(189412 252431,189631 259122)',-1),'Graeme Ave');
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (5,GeometryFromText('LINESTRING(190131 224148,190871 228134)',-1),'Phil Tce');
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (6,GeometryFromText('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>-D</term>
- <listitem>
- <para>Creates a new table and populates it from the Shape file.
- This uses the PostgreSQL "dump" format for the output data
- and 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>
- </variablelist>
- <para>An example session using the loader to create an input file and
- uploading it might look like this:
- </para>
- <programlisting># shp2pgsql shaperoads roadstable roadsdb > roads.sql
+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>-D</term>
+
+ <listitem>
+ <para>Creates a new table and populates it from the Shape file.
+ This uses the PostgreSQL "dump" format for the output data and
+ 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>
+ </variablelist>
+
+ <para>An example session using the loader to create an input file and
+ uploading it might look like this:</para>
+
+ <programlisting># shp2pgsql shaperoads roadstable roadsdb > 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 roadstable roadsdb | 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 id, AsText(geom) AS geom, name FROM ROADS_GEOM;
+
+ <para>A conversion and upload can be done all in one step using UNIX
+ pipes:</para>
+
+ <programlisting># shp2pgsql shaperoads roadstable roadsdb | 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 id, AsText(geom) AS geom, name FROM ROADS_GEOM;
id | geom | name
---+-----------------------------------------+-----------
1 | LINESTRING(191232 243118,191108 243242) | Jeff Rd
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 overlaps 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 "GeometryFromText()" function. So, for example:
- </para>
- <programlisting>SELECT
+(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 overlaps 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 "GeometryFromText()" function. So, for example:</para>
+
+ <programlisting>SELECT
ID, NAME
FROM ROADS_GEOM
WHERE
- GEOM ~= GeometryFromText('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
+ GEOM ~= GeometryFromText('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
ID, NAME
FROM ROADS_GEOM
WHERE
- GEOM && GeometryFromText('POLYGON((191232 243117,191232 243119,191234 243117,191232 243117))',-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
+ GEOM && GeometryFromText('POLYGON((191232 243117,191232 243119,191234 243117,191232 243117))',-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(GEOM) AS GEOM
FROM ROADS_GEOM
WHERE
GEOM && GeometryFromText('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 into a shape file. The basic
- syntax is:
- </para>
- <programlisting>pgsql2shp [<options>] <database> <table></programlisting>
- <para>The commandline options are:</para>
- <variablelist>
- <varlistentry>
- <term>-d</term>
- <listitem>
- <para>Write a 3-dimensional shape file. The default is to write a 2-dimensional shape file.</para>
- </listitem>
- </varlistentry>
- <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>
- </variablelist>
- </sect2>
- </sect1>
- <sect1>
- <title>Building Indexes</title>
- <para>Indexes are what make using a spatial database for large databases
- 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 generalized
- 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] GIST_GEOMETRY_OPS ); </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 < 75 installations
-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 < 75 installations this is done by running
-"update_geometry_stats([table_name, column_name])" (compute distribution)
-and "VACUUM ANALYZE [table_name] [column_name]" (compute number of values).
-Starting with PostgreSQL 75 running "VACUUM ANALYZE" will do both operations.
-You should regularly vacuum your databases anyways -- many PostgreSQL
-DBAs have "VACUUM" 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 "SET ENABLE_SEQSCAN=OFF" 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
- "ENABLE_SEQSCAN" 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 "ENABLE_SEQSCAN".
- </para>
- </note>
- </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 advatage 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 distance( the_geom, GeometryFromText( '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>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 distance( the_geom, GeometryFromText( '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>
- </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]
+ <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 into a shape file. The
+ basic syntax is:</para>
+
+ <programlisting>pgsql2shp [<options>] <database> <table></programlisting>
+
+ <para>The commandline options are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>-d</term>
+
+ <listitem>
+ <para>Write a 3-dimensional shape file. The default is to write
+ a 2-dimensional shape file.</para>
+ </listitem>
+ </varlistentry>
+
+ <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>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Building Indexes</title>
+
+ <para>Indexes are what make using a spatial database for large databases
+ 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 generalized
+ 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] GIST_GEOMETRY_OPS ); </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 < 75 installations
+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 < 75 installations this is done by
+ running "update_geometry_stats([table_name, column_name])"
+ (compute distribution) and "VACUUM ANALYZE [table_name]
+ [column_name]" (compute number of values). Starting with
+ PostgreSQL 75 running "VACUUM ANALYZE" will do both operations.
+ You should regularly vacuum your databases anyways -- many
+ PostgreSQL DBAs have "VACUUM" 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 "SET ENABLE_SEQSCAN=OFF"
+ 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
+ "ENABLE_SEQSCAN" 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 "ENABLE_SEQSCAN".</para>
+ </note>
+ </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 advatage
+ 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 distance( the_geom, GeometryFromText( '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>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 distance( the_geom, GeometryFromText( '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>
+ </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] GIST_GEOMETRY_OPS );</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>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>
- </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
+ </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>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>
+ </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
- acheive 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
+
+ <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
+ acheive 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
+ 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
- END
- END
+
+ <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
+ END
+ 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.*;
+
+ <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.*;
* 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");
+ ((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();
*/
PGgeometry geom = (PGgeometry)r.getObject(1);
int id = r.getInt(2);
- System.out.println("Row " + id + ":");
+ System.out.println("Row " + id + ":");
System.out.println(geom.toString());
}
- s.close();
+ 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);
+}</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);
+ 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());
+ 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>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>
- <sect1>
- <title>OpenGIS Functions</title>
- <variablelist>
- <varlistentry>
- <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>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>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 dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0),POINT(0 0)');
+}</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>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>
+
+ <sect1>
+ <title>OpenGIS Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <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>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>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 dimension('GEOMETRYCOLLECTION(LINESTRING(1 1,0 0),POINT(0 0)');
dimension
-----------
1</programlisting>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>
- <term>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>
- <term>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>equals(geometry)</term>
- <listitem>
- <para>
- Returns 1 (TRUE) if this Geometry is "spatially equal" to
-anotherGeometry. 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>disjoint(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is "spatially disjoint" from anotherGeometry.
- </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>intersects(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry "spatially intersects" anotherGeometry.
- </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 - Intersects(g1, g2 ) --> Not (Disjoint(g1, g2 )) </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>touches(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry "spatially touches" anotherGeometry.
- </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.Touches(b) -> (I(a) intersection I(b) = {empty set} ) and (a intersection b) not empty </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>crosses(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry "spatially crosses" anotherGeometry.
- </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, 'T*T******') </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>within(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is "spatially within" anotherGeometry.
- </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, 'T*F**F***') </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>overlaps(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is "spatially overlapping" anotherGeometry.
- </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>contains(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is "spatially contains" anotherGeometry.
- </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 - same as within(geometry,geometry)</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>intersects(geometry,geometry)</term>
- <listitem>
- <para>Returns 1 (TRUE) if this Geometry is "spatially intersects" anotherGeometry.
- </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>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>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>
- <varlistentry>
- <term>buffer(geometry,double)</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.
- </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>convexhull(geometry)</term>
- <listitem>
- <para> Returns a geometry that represents the convex hull of this Geometry.
- </para>
- <para>Performed by the GEOS module</para>
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>intersection(geometry,geometry)</term>
- <listitem>
- <para> Returns a geometry that represents the point set
-intersection of this Geometry with anotherGeometry.
- </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>
-<!-- Should this be documented? -->
- <varlistentry>
- <term>GeomUnion(geometry,geometry)</term>
- <listitem>
- <para> Returns a geometry that represents the point set union of
-this Geometry with anotherGeometry.
- </para>
- <para>Performed by the GEOS module</para>
- <para>Do not call with a GeometryCollection as an argument</para>
- <para>NOTE: this is renamed from "union" because union is an SQL reserved word</para>
- <para>OGC SPEC s2.1.1.3</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>GeomUnion(geometry set)</term>
- <listitem>
- <para> Returns a geometry that represents the point set union of
-this 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>memGeomUnion(geometry set)</term>
- <listitem>
- <para>Same as the above, only memory-friendly (uses less memory and more processor time).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>symdifference(geometry,geometry)</term>
- <listitem>
- <para> Returns a geometry that represents the point set symmetric difference of this Geometry with anotherGeometry.
- </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>difference(geometry,geometry)</term>
- <listitem>
- <para> Returns a geometry that represents the point set
-symmetric difference of this Geometry with anotherGeometry.
- </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>Envelope(geometry)</term>
- <listitem>
- <para>Returns a POLYGON representing the bounding box of the
- geometry.
- </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>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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>X(geometry)</term>
- <listitem>
- <para>Find and return the X coordinate of the first point in the
- geometry. Return NULL if there is no point in the geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Y(geometry)</term>
- <listitem>
- <para>Find and return the Y coordinate of the first point in the
- geometry. Return NULL if there is no point in the geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Z(geometry)</term>
- <listitem>
- <para>Find and return the Z coordinate of the first point in the
- geometry. Return NULL if there is no point in the geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>ExteriorRing(geometry)</term>
- <listitem>
- <para>Return the exterior ring of the first polygon in the
- geometry. Return NULL if there is no polygon in the geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>InteriorRingN(geometry,integer)</term>
- <listitem>
- <para>Return the N'th interior ring of the first polygon in the
- geometry. Return NULL if there is no polygon in the geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>IsClosed(geometry)</term>
- <listitem>
- <para>Returns true of the geometry start and
- end points are coincident.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>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>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>
- <para>1 is 1st geometry</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Distance(geometry,geometry)</term>
- <listitem>
- <para>Return the cartesian distance between two geometries
- in projected units.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>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>GeometryFromText(varchar, integer)</term>
- <listitem>
- <para>Syntax: GeometryFromText(<geometry>,<SRID>)
- Convert a Well-Known Text representation of a geometry
- into a geometry object.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>GeomFromText(varchar, integer)</term>
- <listitem>
- <para>As above. A synonym for GeometryFromText.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>SetSRID(geometry)</term>
- <listitem>
- <para>Set the SRID on a geometry to a particular integer
- value. Useful in constructing bounding boxes for queries.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>EndPoint(geometry)</term>
- <listitem>
- <para>Returns the last point of the geometry as a point.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>StartPoint(geometry)</term>
- <listitem>
- <para>Returns the first point of the geometry as a point.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>
- </variablelist>
- </sect1>
- <sect1>
- <title>Other 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>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 75 statistics gathering is automatically performed running "VACUUM ANALYZE".</para>
- </listitem>
- </varlistentry>
- <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 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 boux overlaps B's bounding box the operator returns true.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>area2d(geometry)</term>
- <listitem>
- <para>Returns the area of the geometry if it is a polygon or
- multi-polygon.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>area(geometry)</term>
- <listitem>
- <para>Returns the area of the geometry if it is a polygon or
- multi-polygon. (same as area2(<polygon|multipolygon>)
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>asbinary(geometry,'NDR')</term>
- <listitem>
- <para>Returns the geometry in the OGC "well-known-binary" format,
- using little-endian 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>isvalid(geometry)</term>
- <listitem>
- <para>returns true if this geometry is valid.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>asbinary(geometry,'XDR')</term>
- <listitem>
- <para>Returns the geometry in the OGC "well-known-binary" format,
- using big-endian 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>GeomFromText(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>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>GeometryFromText(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>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>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>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>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>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>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>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>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>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>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>GeomFromWKB(text,[<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>GeomFromWKB(text,[<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>PointFromWKB(text,[<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>LineFromWKB(text,[<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>LinestringFromWKB(text,[<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>PolyFromWKB(text,[<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>PolygonFromWKB(text,[<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>MPointFromWKB(text,[<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>MLineFromWKB(text,[<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>MPolyFromWKB(text,[<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>GeomCollFromWKB(text,[<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>
- <term>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>box3d(geometry)</term>
- <listitem>
- <para>Returns a BOX3D representing the maximum extents of the
- geometry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>collect(geometry set)</term>
- <listitem>
- <para>This function returns a GEOMETRYCOLLECTION object from a set
- of geometries. The collect() 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 COLLECT(GEOM) FROM GEOMTABLE GROUP BY ATTRCOLUMN"
- will return a separate GEOMETRYCOLLECTION for each distinct value
- of ATTRCOLUMN.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>memcollect(geometry set)</term>
- <listitem>
- <para>This does the the same of collect(geometry), only more
- memory-friendly (uses less memory and more processor time).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>
- <term>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
- EXTENT(GEOM) FROM GEOMTABLE" will return a BOX3D giving the maximum extend of
- all features in the table. Similarly, "SELECT EXTENT(GEOM) FROM GEOMTABLE GROUP
- BY CATEGORY" will return one extent result for each category.</para>
- </listitem>
- </varlistentry><varlistentry><term>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>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>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_3d">
- <term>force_3d(geometry)</term>
- <listitem>
- <para>Forces the geometries into a "3-dimensional mode" so that all
- output representations will have the X, Y and Z coordinates.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>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>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>length_spheroid(geometry,spheroid)</term>
- <listitem>
- <para>Calculates the length of of a geometry on an elipsoid. This
- is useful if the coordinates of the geometry are in latitude/longitude and a
- length is desired without reprojection. The elipsoid 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>length3d_spheroid(geometry,spheroid)</term>
- <listitem>
- <para>Calculates the length of of a geometry on an elipsoid, 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>max_distance(linestring,linestring)</term>
- <listitem>
- <para>Returns the largest distance between two line strings.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>mem_size(geometry)</term>
- <listitem>
- <para>Returns the amount of space (in bytes) the geometry
- takes.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>npoints(geometry)</term>
- <listitem>
- <para>Returns the number of points in the geometry.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>nrings(geometry)</term>
- <listitem>
- <para>If the geometry is a polygon or multi-polygon returns the
- number of rings.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>numb_sub_objects(geometry)</term>
- <listitem>
- <para>Returns the number of objects stored in the geometry. This is
- useful for MULTI-geometries and GEOMETRYCOLLECTIONs.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>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>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>postgis_version()</term>
- <listitem>
- <para>Returns the version number of the PostGIS functions
- installed in this database (deprecated, use postgis_full_version() instead).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>postgis_lib_version()</term>
- <listitem>
- <para>Returns the version number of the PostGIS library.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>postgis_scripts_installed()</term>
- <listitem>
- <para>Returns the version number of the postgis.sql script installed in this database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>postgis_scripts_released()</term>
- <listitem>
- <para>Returns the version number of the postgis.sql script released with the installed postgis lib.
- </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>
- </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>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>postgis_uses_stats()</term>
- <listitem>
- <para>Returns true if STATS usage has been enabled, false otherwise.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>postgis_full_version()</term>
- <listitem>
- <para>Reports full postgis version and build configuration infos.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>summary(geometry)</term>
- <listitem>
- <para>Returns a text summary of the contents of the
- geometry.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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 SPATIAL_REF_SYS table.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>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>xmin(box3d) ymin(box3d) zmin(box3d)</term>
- <listitem>
- <para>Returns the requested minima of a bounding box.</para>
- </listitem>
- </varlistentry><varlistentry>
- <term>xmax(box3d) ymax(box3d) zmax(box3d)</term>
- <listitem>
- <para>Returns the requested maxima of a bounding box.</para>
- </listitem>
- </varlistentry><varlistentry>
- <term>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 isSimple)</para>
- </listitem>
- </varlistentry><varlistentry>
- <term>line_interpolate_point(geometry, distance)</term>
- <listitem>
- <para>Interpolates a point along a line. First argument must be a LINESTRING. Second argument is a float between 0 and 1. Returns a point.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
- </chapter>
-</book>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>
+ <term>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>
+ <term>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>equals(geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially equal" to
+ anotherGeometry. 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>disjoint(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially disjoint"
+ from anotherGeometry.</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>intersects(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry "spatially intersects"
+ anotherGeometry.</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 - Intersects(g1, g2 ) -->
+ Not (Disjoint(g1, g2 ))</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>touches(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry "spatially touches"
+ anotherGeometry.</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.Touches(b) -> (I(a)
+ intersection I(b) = {empty set} ) and (a intersection b) not
+ empty</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>crosses(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry "spatially crosses"
+ anotherGeometry.</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,
+ 'T*T******')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>within(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially within"
+ anotherGeometry.</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,
+ 'T*F**F***')</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>overlaps(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially overlapping"
+ anotherGeometry.</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>contains(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially contains"
+ anotherGeometry.</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 - same as
+ within(geometry,geometry)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>intersects(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns 1 (TRUE) if this Geometry is "spatially intersects"
+ anotherGeometry.</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>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>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>
+
+ <varlistentry>
+ <term>buffer(geometry,double)</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.</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>convexhull(geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the convex hull of this
+ Geometry.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>intersection(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set
+ intersection of this Geometry with anotherGeometry.</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>
+
+ <!-- Should this be documented? -->
+
+ <varlistentry>
+ <term>GeomUnion(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set union of
+ this Geometry with anotherGeometry.</para>
+
+ <para>Performed by the GEOS module</para>
+
+ <para>Do not call with a GeometryCollection as an argument</para>
+
+ <para>NOTE: this is renamed from "union" because union is an SQL
+ reserved word</para>
+
+ <para>OGC SPEC s2.1.1.3</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GeomUnion(geometry set)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set union of
+ this 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>memGeomUnion(geometry set)</term>
+
+ <listitem>
+ <para>Same as the above, only memory-friendly (uses less memory
+ and more processor time).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>symdifference(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set symmetric
+ difference of this Geometry with anotherGeometry.</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>difference(geometry,geometry)</term>
+
+ <listitem>
+ <para>Returns a geometry that represents the point set symmetric
+ difference of this Geometry with anotherGeometry.</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>Envelope(geometry)</term>
+
+ <listitem>
+ <para>Returns a POLYGON representing the bounding box of the
+ geometry.</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>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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>X(geometry)</term>
+
+ <listitem>
+ <para>Find and return the X coordinate of the first point in the
+ geometry. Return NULL if there is no point in the geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Y(geometry)</term>
+
+ <listitem>
+ <para>Find and return the Y coordinate of the first point in the
+ geometry. Return NULL if there is no point in the geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Z(geometry)</term>
+
+ <listitem>
+ <para>Find and return the Z coordinate of the first point in the
+ geometry. Return NULL if there is no point in the geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ExteriorRing(geometry)</term>
+
+ <listitem>
+ <para>Return the exterior ring of the first polygon in the
+ geometry. Return NULL if there is no polygon in the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>InteriorRingN(geometry,integer)</term>
+
+ <listitem>
+ <para>Return the N'th interior ring of the first polygon in the
+ geometry. Return NULL if there is no polygon in the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IsClosed(geometry)</term>
+
+ <listitem>
+ <para>Returns true of the geometry start and end points are
+ coincident.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>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>
+
+ <para>1 is 1st geometry</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Distance(geometry,geometry)</term>
+
+ <listitem>
+ <para>Return the cartesian distance between two geometries in
+ projected units.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>GeometryFromText(varchar, integer)</term>
+
+ <listitem>
+ <para>Syntax: GeometryFromText(<geometry>,<SRID>)
+ Convert a Well-Known Text representation of a geometry into a
+ geometry object.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GeomFromText(varchar, integer)</term>
+
+ <listitem>
+ <para>As above. A synonym for GeometryFromText.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SetSRID(geometry)</term>
+
+ <listitem>
+ <para>Set the SRID on a geometry to a particular integer value.
+ Useful in constructing bounding boxes for queries.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>EndPoint(geometry)</term>
+
+ <listitem>
+ <para>Returns the last point of the geometry as a point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>StartPoint(geometry)</term>
+
+ <listitem>
+ <para>Returns the first point of the geometry as a point.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>
+ </variablelist>
+ </sect1>
+
+ <sect1>
+ <title>Other 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>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 75 statistics gathering
+ is automatically performed running "VACUUM ANALYZE".</para>
+ </listitem>
+ </varlistentry>
+
+ <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 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 boux overlaps B's bounding box the operator returns
+ true.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>area2d(geometry)</term>
+
+ <listitem>
+ <para>Returns the area of the geometry if it is a polygon or
+ multi-polygon.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>area(geometry)</term>
+
+ <listitem>
+ <para>Returns the area of the geometry if it is a polygon or
+ multi-polygon. (same as area2(<polygon|multipolygon>)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>asbinary(geometry,'NDR')</term>
+
+ <listitem>
+ <para>Returns the geometry in the OGC "well-known-binary" format,
+ using little-endian 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>isvalid(geometry)</term>
+
+ <listitem>
+ <para>returns true if this geometry is valid.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>asbinary(geometry,'XDR')</term>
+
+ <listitem>
+ <para>Returns the geometry in the OGC "well-known-binary" format,
+ using big-endian 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>GeomFromText(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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GeometryFromText(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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>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>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>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>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>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>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>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>GeomFromWKB(text,[<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>GeomFromWKB(text,[<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>PointFromWKB(text,[<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>LineFromWKB(text,[<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>LinestringFromWKB(text,[<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>PolyFromWKB(text,[<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>PolygonFromWKB(text,[<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>MPointFromWKB(text,[<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>MLineFromWKB(text,[<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>MPolyFromWKB(text,[<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>GeomCollFromWKB(text,[<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>
+ <term>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>box3d(geometry)</term>
+
+ <listitem>
+ <para>Returns a BOX3D representing the maximum extents of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>collect(geometry set)</term>
+
+ <listitem>
+ <para>This function returns a GEOMETRYCOLLECTION object from a set
+ of geometries. The collect() 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 COLLECT(GEOM) FROM GEOMTABLE GROUP BY
+ ATTRCOLUMN" will return a separate GEOMETRYCOLLECTION for each
+ distinct value of ATTRCOLUMN.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>memcollect(geometry set)</term>
+
+ <listitem>
+ <para>This does the the same of collect(geometry), only more
+ memory-friendly (uses less memory and more processor time).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>
+ <term>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 EXTENT(GEOM) FROM GEOMTABLE" will return a BOX3D
+ giving the maximum extend of all features in the table. Similarly,
+ "SELECT EXTENT(GEOM) FROM GEOMTABLE GROUP BY CATEGORY" will return
+ one extent result for each category.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>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_3d">
+ <term>force_3d(geometry)</term>
+
+ <listitem>
+ <para>Forces the geometries into a "3-dimensional mode" so that
+ all output representations will have the X, Y and Z
+ coordinates.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>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>length_spheroid(geometry,spheroid)</term>
+
+ <listitem>
+ <para>Calculates the length of of a geometry on an elipsoid. This
+ is useful if the coordinates of the geometry are in
+ latitude/longitude and a length is desired without reprojection.
+ The elipsoid 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>length3d_spheroid(geometry,spheroid)</term>
+
+ <listitem>
+ <para>Calculates the length of of a geometry on an elipsoid,
+ 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>max_distance(linestring,linestring)</term>
+
+ <listitem>
+ <para>Returns the largest distance between two line
+ strings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mem_size(geometry)</term>
+
+ <listitem>
+ <para>Returns the amount of space (in bytes) the geometry
+ takes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>npoints(geometry)</term>
+
+ <listitem>
+ <para>Returns the number of points in the geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nrings(geometry)</term>
+
+ <listitem>
+ <para>If the geometry is a polygon or multi-polygon returns the
+ number of rings.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>numb_sub_objects(geometry)</term>
+
+ <listitem>
+ <para>Returns the number of objects stored in the geometry. This
+ is useful for MULTI-geometries and GEOMETRYCOLLECTIONs.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>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>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>postgis_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the PostGIS functions
+ installed in this database (deprecated, use postgis_full_version()
+ instead).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_lib_version()</term>
+
+ <listitem>
+ <para>Returns the version number of the PostGIS library.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_scripts_installed()</term>
+
+ <listitem>
+ <para>Returns the version number of the postgis.sql script
+ installed in this database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_scripts_released()</term>
+
+ <listitem>
+ <para>Returns the version number of the postgis.sql script
+ released with the installed postgis lib.</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>
+ </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>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_uses_stats()</term>
+
+ <listitem>
+ <para>Returns true if STATS usage has been enabled, false
+ otherwise.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>postgis_full_version()</term>
+
+ <listitem>
+ <para>Reports full postgis version and build configuration
+ infos.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>summary(geometry)</term>
+
+ <listitem>
+ <para>Returns a text summary of the contents of the
+ geometry.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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 SPATIAL_REF_SYS table.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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>xmin(box3d) ymin(box3d) zmin(box3d)</term>
+
+ <listitem>
+ <para>Returns the requested minima of a bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>xmax(box3d) ymax(box3d) zmax(box3d)</term>
+
+ <listitem>
+ <para>Returns the requested maxima of a bounding box.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>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 isSimple)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>line_interpolate_point(geometry, distance)</term>
+
+ <listitem>
+ <para>Interpolates a point along a line. First argument must be a
+ LINESTRING. Second argument is a float between 0 and 1. Returns a
+ point.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect1>
+ </chapter>
+</book>
\ No newline at end of file
projects / postgis / commitdiff