2004-08-28 23:00:33 +00:00
|
|
|
<?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>
|
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<listitem>
|
|
|
|
<para>More information about the GEOS geometry operations library is
|
|
|
|
available at<ulink url="http://www.remotesensing.org/proj">
|
|
|
|
http://geos.refractions.net</ulink>.</para>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>More information about the Proj4 reprojection library is
|
|
|
|
available at <ulink
|
|
|
|
url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
|
|
|
|
</listitem>
|
|
|
|
|
2004-08-28 23:00:33 +00:00
|
|
|
<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>
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>More information about GiST indexing is available at the
|
|
|
|
PostgreSQL GiST development site, <ulink
|
2004-08-28 23:00:33 +00:00
|
|
|
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>
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>(Recommended) Proj4 reprojection library. The Proj4 library is
|
2004-08-28 23:00:33 +00:00
|
|
|
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>
|
2004-09-04 19:58:05 +00:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>(Recommended) GEOS geometry library. The GEOS library is used
|
|
|
|
to provide geometry tests (Touches(), Contains(), Intersects()) and
|
|
|
|
operations (Buffer(), GeomUnion(), Difference()) within PostGIS.
|
|
|
|
GEOS is available for download from <ulink
|
|
|
|
url="http://www.remotesensing.org/proj">http://geos.refractions.net</ulink>.</para>
|
|
|
|
</listitem>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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>
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>Before you can compile the PostGIS server modules, you must
|
2004-08-28 23:00:33 +00:00
|
|
|
compile and install the PostgreSQL package.</para>
|
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<note>
|
|
|
|
<para>If you plan to use GEOS functionality you might need to
|
|
|
|
explicitly link PostgreSQL against the standard C++
|
|
|
|
library:</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>This is a workaround for bogus C++ exceptions interaction
|
|
|
|
with older development tools. If you experience weird problems
|
|
|
|
(backend unexpectedly closed or similar things) try this trick.
|
|
|
|
This will require recompiling your PostgreSQL from scratch, of
|
|
|
|
course.</para>
|
|
|
|
</note>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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 want support for coordinate reprojection you must have
|
|
|
|
the Proj4 library installed, set the <varname>USE_PROJ</varname>
|
2004-09-04 19:58:05 +00:00
|
|
|
variable to <emphasis>1</emphasis>, and adjust the
|
|
|
|
<varname>PROJ_DIR</varname> variable to point to your Proj4
|
|
|
|
installation directory.</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>If want to use GEOS functionality you must have the GEOS
|
2004-08-28 23:00:33 +00:00
|
|
|
library installed, set the <varname>USE_GEOS</varname> variable
|
2004-09-04 19:58:05 +00:00
|
|
|
to <emphasis>1</emphasis>, and adjust the
|
|
|
|
<varname>GEOS_DIR</varname> variable to point to your GEOS
|
|
|
|
installation directory.</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</listitem>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>Run the compile and install commands.</para>
|
|
|
|
|
|
|
|
<programlisting># make
|
2002-11-20 21:32:12 +00:00
|
|
|
# make install</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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>
|
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<programlisting># pg_dump -t spatialtable -f dumpfile.sql yourdatabase
|
2001-09-18 01:34:02 +00:00
|
|
|
# dropdb yourdatabase
|
|
|
|
# createdb yourdatabase
|
2002-05-04 22:46:50 +00:00
|
|
|
# createlang plpgsql yourdatabse
|
2001-09-18 01:34:02 +00:00
|
|
|
# psql -f postgis.sql -d yourdatabase
|
|
|
|
# psql -f dumpfile.sql -d yourdatabase
|
2002-11-20 21:32:12 +00:00
|
|
|
# vacuumdb -z yourdatabase</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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
|
2004-09-04 19:58:05 +00:00
|
|
|
<varname>PGSQL_SRC</varname> environment variable to the path to
|
2004-08-28 23:00:33 +00:00
|
|
|
the PostgreSQL source directory. This will allow you to compile
|
2004-09-04 19:58:05 +00:00
|
|
|
PostGIS, but the <command>make install</command> may not work, so
|
|
|
|
be prepared to copy the PostGIS library and executable files to
|
2004-08-28 23:00:33 +00:00
|
|
|
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>
|
2004-09-04 19:58:05 +00:00
|
|
|
|
|
|
|
<para>If you are running an RPM based distribution, you can check
|
|
|
|
for the existence of pre-installed packages using the
|
|
|
|
<command>rpm</command> command as follows: <command>rpm -qa | grep
|
|
|
|
postgresql</command></para>
|
2004-08-28 23:00:33 +00:00
|
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
<para>Also check that you have made any necessary changes to the top
|
|
|
|
of the Makefile. This includes:</para>
|
|
|
|
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>If you want to be able to do coordinate reprojections, you
|
2004-09-04 19:58:05 +00:00
|
|
|
must install the Proj4 library on your system, set the
|
2004-08-28 23:00:33 +00:00
|
|
|
<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
|
2002-05-04 22:46:50 +00:00
|
|
|
# make
|
2002-11-20 21:32:12 +00:00
|
|
|
# make install</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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
|
2004-09-04 19:58:05 +00:00
|
|
|
tables into ESRI Shape files.</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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) );
|
2002-11-20 21:32:12 +00:00
|
|
|
SELECT AddGeometryColumn('dbname','gtest','geom',-1,'LINESTRING',2);</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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
|
2001-06-22 17:39:29 +00:00
|
|
|
----+----------------+-----------------------------
|
2004-08-28 23:00:33 +00:00
|
|
|
1 | First Geometry | LINESTRING(2 3,4 5,6 5,7 8)
|
2002-11-20 21:32:12 +00:00
|
|
|
(1 row)</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</answer>
|
|
|
|
</qandaentry>
|
|
|
|
|
|
|
|
<qandaentry>
|
|
|
|
<question>
|
|
|
|
<para>How do I construct a spatial query?</para>
|
|
|
|
</question>
|
|
|
|
|
|
|
|
<answer>
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>The same way you construct any other database query, as an SQL
|
|
|
|
combination of return values, functions, and boolean tests.</para>
|
|
|
|
|
|
|
|
<para>For spatial queries, there are two issues that are important
|
|
|
|
to keep in mind while constructing your query: is there a spatial
|
|
|
|
index you can make use of; and, are you doing expensive calculations
|
|
|
|
on a large number of geometries.</para>
|
|
|
|
|
|
|
|
<para>In general, you will want to use the "intersects operator"
|
|
|
|
(&&) which tests whether the bounding boxes of features
|
|
|
|
intersect. The reason the && operator is useful is because
|
|
|
|
if a spatial index is available to speed up the test, the &&
|
|
|
|
operator will make use of this. This can make queries much much
|
|
|
|
faster.</para>
|
|
|
|
|
|
|
|
<para>You will also make use of spatial functions, such as
|
|
|
|
Distance(), Intersects(), Contains() and Within(), among others, to
|
|
|
|
narrow down the results of your search. Most spatial queries include
|
|
|
|
both an indexed test and a spatial function test. The index test
|
|
|
|
serves to limit the number of return tuples to only tuples that
|
|
|
|
<emphasis>might</emphasis> meet the condition of interest. The
|
|
|
|
spatial functions are then use to test the condition exactly.</para>
|
|
|
|
|
|
|
|
<programlisting>SELECT id, the_geom FROM thetable
|
|
|
|
WHERE
|
|
|
|
the_geom && 'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))'
|
|
|
|
AND
|
|
|
|
Contains(the_geom,'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))';</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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
|
2004-09-04 19:58:05 +00:00
|
|
|
support) so having a good index is important.</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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]
|
2004-09-04 19:58:05 +00:00
|
|
|
USING GIST ( [geometrycolumn] );</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<para>The "USING GIST" option tells the server to use a GiST
|
2004-09-04 19:58:05 +00:00
|
|
|
(Generalized Search Tree) index.</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>For PostgreSQL version 7.1.x, you must 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>You should also ensure that the PostgreSQL query planner has
|
|
|
|
enough information about your index to make rational decisions about
|
|
|
|
when to use it. To do this, you have to "gather statistics" on your
|
|
|
|
geometry tables.</para>
|
|
|
|
|
|
|
|
<para>For PostgreSQL 8.0.x and greater, just run the <command>VACUUM
|
|
|
|
ANALYZE</command> command.</para>
|
|
|
|
|
|
|
|
<para>For PostgreSQL 7.4.x and below, run the <command>SELECT
|
|
|
|
UPDATE_GEOMETRY_STATS()</command> command.</para>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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>
|
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<para>The <varname>Expand()</varname> function is a handy way of
|
|
|
|
enlarging a bounding box to allow an index search of a region of
|
|
|
|
interest. The combination of a fast access index clause and a slower
|
|
|
|
accurate distance test provides the best combination of speed and
|
|
|
|
precision for this query.</para>
|
|
|
|
|
2004-08-28 23:00:33 +00:00
|
|
|
<para>For example, to find all objects with 100 meters of POINT(1000
|
|
|
|
1000) the following query would work well:</para>
|
|
|
|
|
|
|
|
<programlisting>SELECT *
|
2002-05-04 22:46:50 +00:00
|
|
|
FROM GEOTABLE
|
|
|
|
WHERE
|
2004-09-04 19:58:05 +00:00
|
|
|
GEOCOLUMN && Expand(GeometryFromText('POINT(1000 1000)',-1),100)
|
2002-05-04 22:46:50 +00:00
|
|
|
AND
|
2004-09-04 19:58:05 +00:00
|
|
|
Distance(GeometryFromText('POINT(1000 1000)',-1),GEOCOLUMN) < 100;</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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 )
|
2002-11-20 21:32:12 +00:00
|
|
|
VALUES (
|
2001-09-18 01:34:02 +00:00
|
|
|
GeometryFromText('POINT(-126.4 45.32)', 312),
|
|
|
|
'A Place'
|
2004-08-28 23:00:33 +00:00
|
|
|
)</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;
|
2001-09-18 01:34:02 +00:00
|
|
|
OGCGeom
|
|
|
|
-------------------------------------------------
|
|
|
|
LINESTRING(-123.741378393049 48.9124018962261,-123.741587115639 48.9123981907507)
|
|
|
|
(1 row)
|
|
|
|
|
|
|
|
db=> SELECT geom AS PostGISGeom FROM thetable;
|
|
|
|
PostGISGeom
|
|
|
|
-------------------------------------------------
|
|
|
|
SRID=123;LINESTRING(-123.741378393049 48.9124018962261,-123.741587115639 48.9123981907507)
|
2002-11-20 21:32:12 +00:00
|
|
|
(1 row)</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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 (
|
2001-09-18 01:34:02 +00:00
|
|
|
SRID INTEGER NOT NULL PRIMARY KEY,
|
|
|
|
AUTH_NAME VARCHAR(256),
|
|
|
|
AUTH_SRID INTEGER,
|
2002-05-04 22:46:50 +00:00
|
|
|
SRTEXT VARCHAR(2048),
|
|
|
|
PROJ4TEXT VARCHAR(2048)
|
2004-08-28 23:00:33 +00:00
|
|
|
)</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",
|
2001-09-18 01:34:02 +00:00
|
|
|
GEOGCS["NAD83",
|
2004-08-28 23:00:33 +00:00
|
|
|
DATUM["North_American_Datum_1983",
|
2001-09-18 01:34:02 +00:00
|
|
|
SPHEROID["GRS 1980",6378137,298.257222101]
|
2004-08-28 23:00:33 +00:00
|
|
|
],
|
2001-09-18 01:34:02 +00:00
|
|
|
PRIMEM["Greenwich",0],
|
|
|
|
UNIT["degree",0.0174532925199433]
|
|
|
|
],
|
2004-08-28 23:00:33 +00:00
|
|
|
PROJECTION["Transverse_Mercator"],
|
2001-09-18 01:34:02 +00:00
|
|
|
PARAMETER["latitude_of_origin",0],
|
2004-08-28 23:00:33 +00:00
|
|
|
PARAMETER["central_meridian",-123],
|
2001-09-18 01:34:02 +00:00
|
|
|
PARAMETER["scale_factor",0.9996],
|
2004-08-28 23:00:33 +00:00
|
|
|
PARAMETER["false_easting",500000],
|
2001-09-18 01:34:02 +00:00
|
|
|
PARAMETER["false_northing",0],
|
2004-08-28 23:00:33 +00:00
|
|
|
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 (
|
2001-09-18 01:34:02 +00:00
|
|
|
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,
|
2004-08-28 23:00:33 +00:00
|
|
|
COORD_DIMENSION INTEGER NOT NULL,
|
2001-09-18 01:34:02 +00:00
|
|
|
SRID INTEGER NOT NULL,
|
|
|
|
TYPE VARCHAR(30) NOT NULL
|
2004-08-28 23:00:33 +00:00
|
|
|
)</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;
|
2002-05-04 22:46:50 +00:00
|
|
|
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (1,GeometryFromText('LINESTRING(191232 243118,191108 243242)',-1),'Jeff Rd');
|
2001-09-18 01:34:02 +00:00
|
|
|
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');
|
2002-05-04 22:46:50 +00:00
|
|
|
INSERT INTO ROADS_GEOM (ID,GEOM,NAME ) VALUES (6,GeometryFromText('LINESTRING(198231 263418,198213 268322)',-1),'Dave Cres');
|
2004-08-28 23:00:33 +00:00
|
|
|
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
|
2002-11-20 21:32:12 +00:00
|
|
|
# psql -d roadsdb -f roads.sql</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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;
|
2001-09-18 01:34:02 +00:00
|
|
|
id | geom | name
|
|
|
|
---+-----------------------------------------+-----------
|
|
|
|
1 | LINESTRING(191232 243118,191108 243242) | Jeff Rd
|
|
|
|
2 | LINESTRING(189141 244158,189265 244817) | Geordie Rd
|
|
|
|
3 | LINESTRING(192783 228138,192612 229814) | Paul St
|
|
|
|
4 | LINESTRING(189412 252431,189631 259122) | Graeme Ave
|
|
|
|
5 | LINESTRING(190131 224148,190871 228134) | Phil Tce
|
|
|
|
6 | LINESTRING(198231 263418,198213 268322) | Dave Cres
|
2002-05-04 22:46:50 +00:00
|
|
|
7 | LINESTRING(218421 284121,224123 241231) | Chris Way
|
2004-08-28 23:00:33 +00:00
|
|
|
(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
|
2002-05-04 22:46:50 +00:00
|
|
|
ID, NAME
|
|
|
|
FROM ROADS_GEOM
|
|
|
|
WHERE
|
2004-08-28 23:00:33 +00:00
|
|
|
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
|
2002-05-04 22:46:50 +00:00
|
|
|
ID, NAME
|
|
|
|
FROM ROADS_GEOM
|
|
|
|
WHERE
|
2004-08-28 23:00:33 +00:00
|
|
|
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
|
2002-05-04 22:46:50 +00:00
|
|
|
AsText(GEOM) AS GEOM
|
|
|
|
FROM ROADS_GEOM
|
|
|
|
WHERE
|
2002-11-20 21:32:12 +00:00
|
|
|
GEOM && GeometryFromText('BOX3D(191232 243117,191232 243119)'::box3d,-1);</programlisting>
|
2004-06-16 13:14:01 +00:00
|
|
|
|
2004-08-28 23:00:33 +00:00
|
|
|
<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>
|
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
<para><programlisting>VACUUM ANALYZE [table_name] [column_name];
|
2004-08-28 23:00:33 +00:00
|
|
|
|
2004-09-04 19:58:05 +00:00
|
|
|
-- This is only needed for PostgreSQL 7.4 installations and below
|
2004-08-28 23:00:33 +00:00
|
|
|
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
|
2004-09-04 19:58:05 +00:00
|
|
|
usage. For PostgreSQL 7.4 installations and below this is done by
|
2004-08-28 23:00:33 +00:00
|
|
|
running "update_geometry_stats([table_name, column_name])"
|
|
|
|
(compute distribution) and "VACUUM ANALYZE [table_name]
|
|
|
|
[column_name]" (compute number of values). Starting with
|
2004-09-04 19:58:05 +00:00
|
|
|
PostgreSQL 8.0 running "VACUUM ANALYZE" will do both operations.
|
2004-08-28 23:00:33 +00:00
|
|
|
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]
|
2002-11-22 21:22:22 +00:00
|
|
|
USING GIST ( [geometrycolumn] GIST_GEOMETRY_OPS );</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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
|
2002-11-22 21:22:22 +00:00
|
|
|
END</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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
|
2002-11-22 21:22:22 +00:00
|
|
|
END
|
|
|
|
|
|
|
|
LAYER
|
2004-08-28 23:00:33 +00:00
|
|
|
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
|
2002-11-22 21:22:22 +00:00
|
|
|
END</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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
|
2002-11-22 21:22:22 +00:00
|
|
|
END</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
|
|
|
|
<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.*;
|
2001-09-18 01:34:02 +00:00
|
|
|
import java.util.*;
|
|
|
|
import java.lang.*;
|
|
|
|
import org.postgis.*;
|
2001-06-22 17:39:29 +00:00
|
|
|
|
2001-09-18 01:34:02 +00:00
|
|
|
public class JavaGIS {
|
|
|
|
public static void main(String[] args)
|
|
|
|
{
|
|
|
|
java.sql.Connection conn;
|
|
|
|
try
|
|
|
|
{
|
|
|
|
/*
|
|
|
|
* Load the JDBC driver and establish a connection.
|
|
|
|
*/
|
|
|
|
Class.forName("org.postgresql.Driver");
|
|
|
|
String url = "jdbc:postgresql://localhost:5432/database";
|
|
|
|
conn = DriverManager.getConnection(url, "postgres", "");
|
|
|
|
|
|
|
|
/*
|
|
|
|
* Add the geometry types to the connection. Note that you
|
|
|
|
* must cast the connection to the pgsql-specific connection * implementation before calling the addDataType() method.
|
2001-06-22 17:39:29 +00:00
|
|
|
*/
|
2004-08-28 23:00:33 +00:00
|
|
|
((org.postgresql.Connection)conn).addDataType("geometry","org.postgis.PGgeometry");
|
|
|
|
((org.postgresql.Connection)conn).addDataType("box3d","org.postgis.PGbox3d");
|
2001-09-18 01:34:02 +00:00
|
|
|
|
2004-08-28 23:00:33 +00:00
|
|
|
/*
|
2001-09-18 01:34:02 +00:00
|
|
|
* Create a statement and execute a select query.
|
|
|
|
*/
|
|
|
|
Statement s = conn.createStatement();
|
|
|
|
ResultSet r = s.executeQuery("select AsText(geom) as geom,id from geomtable");
|
|
|
|
while( r.next() )
|
|
|
|
{
|
|
|
|
/*
|
|
|
|
* Retrieve the geometry as an object then cast it to the geometry type.
|
|
|
|
* Print things out.
|
|
|
|
*/
|
|
|
|
PGgeometry geom = (PGgeometry)r.getObject(1);
|
|
|
|
int id = r.getInt(2);
|
2004-08-28 23:00:33 +00:00
|
|
|
System.out.println("Row " + id + ":");
|
2001-09-18 01:34:02 +00:00
|
|
|
System.out.println(geom.toString());
|
|
|
|
}
|
2004-08-28 23:00:33 +00:00
|
|
|
s.close();
|
2001-09-18 01:34:02 +00:00
|
|
|
conn.close();
|
|
|
|
}
|
|
|
|
catch( Exception e )
|
|
|
|
{
|
|
|
|
e.printStackTrace();
|
|
|
|
}
|
2001-06-22 17:39:29 +00:00
|
|
|
}
|
2004-08-28 23:00:33 +00:00
|
|
|
}</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);
|
2001-09-18 01:34:02 +00:00
|
|
|
if( geom.getType() = Geometry.POLYGON )
|
|
|
|
{
|
2001-06-22 17:39:29 +00:00
|
|
|
Polygon pl = (Polygon)geom.getGeometry();
|
2001-09-18 01:34:02 +00:00
|
|
|
for( int r = 0; r < pl.numRings(); r++ )
|
|
|
|
{
|
2001-06-22 17:39:29 +00:00
|
|
|
LinearRing rng = pl.getRing(r);
|
2004-08-28 23:00:33 +00:00
|
|
|
System.out.println("Ring: " + r);
|
2001-09-18 01:34:02 +00:00
|
|
|
for( int p = 0; p < rng.numPoints(); p++ )
|
|
|
|
{
|
|
|
|
Point pt = rng.getPoint(p);
|
2001-06-22 17:39:29 +00:00
|
|
|
System.out.println("Point: " + p);
|
2004-08-28 23:00:33 +00:00
|
|
|
System.out.println(pt.toString());
|
2001-09-18 01:34:02 +00:00
|
|
|
}
|
|
|
|
}
|
2004-08-28 23:00:33 +00:00
|
|
|
}</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)');
|
2003-08-08 18:19:20 +00:00
|
|
|
dimension
|
|
|
|
-----------
|
|
|
|
1</programlisting>
|
2004-08-28 23:00:33 +00:00
|
|
|
</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
|
2004-09-04 19:58:05 +00:00
|
|
|
complete. NOTE: starting with PostgreSQL 8.0 statistics gathering
|
2004-08-28 23:00:33 +00:00
|
|
|
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>
|