Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #12930, #12832, #11538 -- Refactored and merged the GeoDjango d…

…ocumentation into the rest of the Django docs.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12856 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 459c71e3320b17bb4e0f3188baf7ca3ff1bd2260 1 parent 667ced2
@jbronn jbronn authored
Showing with 7,101 additions and 5 deletions.
  1. +57 −0 docs/ref/contrib/gis/admin.txt
  2. +83 −0 docs/ref/contrib/gis/commands.txt
  3. +9 −0 docs/ref/contrib/gis/create_template_postgis-1.3.sh
  4. +9 −0 docs/ref/contrib/gis/create_template_postgis-1.4.sh
  5. +9 −0 docs/ref/contrib/gis/create_template_postgis-1.5.sh
  6. +9 −0 docs/ref/contrib/gis/create_template_postgis-debian.sh
  7. +304 −0 docs/ref/contrib/gis/db-api.txt
  8. +99 −0 docs/ref/contrib/gis/deployment.txt
  9. +97 −0 docs/ref/contrib/gis/feeds.txt
  10. +1,114 −0 docs/ref/contrib/gis/gdal.txt
  11. +223 −0 docs/ref/contrib/gis/geoip.txt
  12. +1,256 −0 docs/ref/contrib/gis/geoquerysets.txt
  13. +911 −0 docs/ref/contrib/gis/geos.txt
  14. +33 −0 docs/ref/contrib/gis/index.txt
  15. +1,190 −0 docs/ref/contrib/gis/install.txt
  16. +219 −0 docs/ref/contrib/gis/layermapping.txt
  17. +180 −0 docs/ref/contrib/gis/measure.txt
  18. +266 −0 docs/ref/contrib/gis/model-api.txt
  19. +20 −0 docs/ref/contrib/gis/ogrinspect.txt
  20. +27 −0 docs/ref/contrib/gis/sitemaps.txt
  21. +181 −0 docs/ref/contrib/gis/testing.txt
  22. +758 −0 docs/ref/contrib/gis/tutorial.txt
  23. +32 −0 docs/ref/contrib/gis/utils.txt
  24. +9 −0 docs/ref/contrib/index.txt
  25. +6 −5 docs/topics/db/managers.txt
View
57 docs/ref/contrib/gis/admin.txt
@@ -0,0 +1,57 @@
+.. _ref-gis-admin:
+
+======================
+GeoDjango's admin site
+======================
+
+.. module:: django.contrib.gis.admin
+ :synopsis: GeoDjango's extensions to the admin site.
+
+
+``GeoModelAdmin``
+=================
+
+.. class:: GeoModelAdmin
+
+ .. attribute:: default_lon
+
+ The default center longitude.
+
+ .. attribute:: default_lat
+
+ The default center latitude.
+
+ .. attribute:: default_zoom
+
+ The default zoom level to use. Defaults to 18.
+
+ .. attribute:: extra_js
+
+ Sequence of URLs to any extra JavaScript to include.
+
+ .. attribute:: map_template
+
+ Override the template used to generate the JavaScript slippy map.
+ Default is ``'gis/admin/openlayers.html'``.
+
+ .. attribute:: map_width
+
+ Width of the map, in pixels. Defaults to 600.
+
+ .. attribute:: map_height
+
+ Height of the map, in pixels. Defaults to 400.
+
+ .. attribute:: openlayers_url
+
+ Link to the URL of the OpenLayers JavaScript. Defaults to
+ ``'http://openlayers.org/api/2.8/OpenLayers.js'``.
+
+``OSMGeoAdmin``
+===============
+
+.. class:: OSMGeoAdmin
+
+ A subclass of :class:`GeoModelAdmin` that uses a spherical mercator projection
+ with OpenStreetMap street data tiles. See the :ref:`OSMGeoAdmin introduction <osmgeoadmin-intro>`
+ in the tutorial for a usage example.
View
83 docs/ref/contrib/gis/commands.txt
@@ -0,0 +1,83 @@
+.. ref-geodjango-admin:
+
+=============================
+GeoDjango Management Commands
+=============================
+
+inspectdb
+=========
+
+.. describe:: django-admin.py inspectdb
+
+When :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`, the
+:djadmin:`inspectdb` management command is overridden with one from GeoDjango.
+The overridden command is spatially-aware, and places geometry fields in the
+auto-generated model definition, where appropriate.
+
+ogrinspect <data_source> <model_name>
+=====================================
+
+.. django-admin:: ogrinspect
+
+The ``ogrinpsect`` management command will inspect the given OGR-compatible
+:class:`~django.contrib.gis.gdal.DataSource` (e.g., a shapefile) and will
+output a GeoDjango model with the given model name. There's a detailed example
+of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`.
+
+.. django-admin-option:: --blank <blank_field(s)>
+
+ Use a comma separated list of OGR field names to add the ``blank=True``
+ keyword option to the field definition. Set with ``true`` to apply
+ to all applicable fields.
+
+.. django-admin-option:: --decimal <decimal_field(s)>
+
+ Use a comma separated list of OGR float fields to generate
+ :class:`~django.db.models.DecimalField` instead of the default
+ :class:`~django.db.models.FloatField`. Set to ``true`` to apply to all
+ OGR float fields.
+
+.. django-admin-option:: --geom-name <name>
+
+ Specifies the model attribute name to use for the geometry field.
+ Defaults to ``'geom'``.
+
+.. django-admin-option:: --layer <layer>
+
+ The key for specifying which layer in the OGR
+ :class:`~django.contrib.gis.gdal.DataSource` source to use.
+ Defaults to 0 (the first layer). May be an integer or a string identifier
+ for the :class:`~django.contrib.gis.gdal.Layer`.
+
+.. django-admin-option:: --mapping
+
+ Automatically generate a mapping dictionary for use with
+ :class:`~django.contrib.gis.utils.LayerMapping`.
+
+.. django-admin-option:: --multi-geom
+
+ When generating the geometry field, treat it as a geometry collection.
+ For example, if this setting is enabled then a
+ :class:`~django.contrib.gis.db.models.MultiPolygonField` will be placed
+ in the generated model rather than
+ :class:`~django.contrib.gis.db.models.PolygonField`.
+
+.. django-admin-option:: --name-field <name_field>
+
+ Generates a ``__unicode__`` routine on the model that will return the
+ the given field name.
+
+.. django-admin-option:: --no-imports
+
+ Suppresses the ``from django.contrib.gis.db import models`` import statement.
+
+.. django-admin-option:: --null <null_field(s)>
+
+ Use a comma separated list of OGR field names to add the ``null=True``
+ keyword option to the field definition. Set with ``true`` to apply to
+ all applicable fields.
+
+.. django-admin-option:: --srid
+
+ The SRID to use for the geometry field. If not set, ``ogrinspect`` attempts
+ to automatically determine of the SRID of the data source.
View
9 docs/ref/contrib/gis/create_template_postgis-1.3.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
View
9 docs/ref/contrib/gis/create_template_postgis-1.4.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.4
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
View
9 docs/ref/contrib/gis/create_template_postgis-1.5.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=`pg_config --sharedir`/contrib/postgis-1.5
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
View
9 docs/ref/contrib/gis/create_template_postgis-debian.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+POSTGIS_SQL_PATH=/usr/share/postgresql-8.3-postgis
+createdb -E UTF8 template_postgis # Create the template spatial database.
+createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
+psql -d postgres -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
+psql -d template_postgis -f $POSTGIS_SQL_PATH/lwpostgis.sql # Loading the PostGIS SQL routines
+psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
+psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;" # Enabling users to alter spatial tables.
+psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
View
304 docs/ref/contrib/gis/db-api.txt
@@ -0,0 +1,304 @@
+.. _ref-gis-db-api:
+
+======================
+GeoDjango Database API
+======================
+
+.. module:: django.contrib.gis.db.models
+ :synopsis: GeoDjango's database API.
+
+.. _spatial-backends:
+
+Spatial Backends
+================
+
+.. versionadded:: 1.2
+
+In Django 1.2, support for :ref:`multiple databases <topics-db-multi-db>` was
+introduced. In order to support multiple databases, GeoDjango has segregated
+its functionality into full-fledged spatial database backends:
+
+* :mod:`django.contrib.gis.db.backends.postgis`
+* :mod:`django.contrib.gis.db.backends.mysql`
+* :mod:`django.contrib.gis.db.backends.oracle`
+* :mod:`django.contrib.gis.db.backends.spatialite`
+
+Backwards-Compatibility
+-----------------------
+
+For those using the old database settings (e.g., the ``DATABASE_*`` settings)
+Django 1.2 will automatically use the appropriate spatial backend as long
+as :mod:`django.contrib.gis` is in your :setting:`INSTALLED_APPS`. For
+example, if you have the following in your settings::
+
+ DATABASE_ENGINE='postgresql_psycopg2'
+
+ ...
+
+ INSTALLED_APPS = (
+ ...
+ 'django.contrib.gis',
+ ...
+ )
+
+Then, :mod:`django.contrib.gis.db.backends.postgis` will automatically be used as your
+spatial backend.
+
+Creating and Saving Geographic Models
+=====================================
+Here is an example of how to create a geometry object (assuming the ``Zipcode``
+model)::
+
+ >>> from zipcode.models import Zipcode
+ >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
+ >>> z.save()
+
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects may also be used to save geometric models::
+
+ >>> from django.contrib.gis.geos import GEOSGeometry
+ >>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
+ >>> z = Zipcode(code=77096, poly=poly)
+ >>> z.save()
+
+Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a
+different SRID value) than that of the field, then it will be implicitly
+transformed into the SRID of the model's field, using the spatial database's
+transform procedure::
+
+ >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
+ >>> z = Zipcode(code=78212, poly=poly_3084)
+ >>> z.save()
+ >>> from django.db import connection
+ >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True)
+ INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
+
+Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT
+(Well Known Text [#fnwkt]_), HEXEWKB (PostGIS specific -- a WKB geometry in
+hexadecimal [#fnewkb]_), and GeoJSON [#fngeojson]_ (requires GDAL). Essentially,
+if the input is not a ``GEOSGeometry`` object, the geometry field will attempt to
+create a ``GEOSGeometry`` instance from the input.
+
+For more information creating :class:`~django.contrib.gis.geos.GEOSGeometry`
+objects, refer to the :ref:`GEOS tutorial <geos-tutorial>`.
+
+.. _spatial-lookups-intro:
+
+Spatial Lookups
+===============
+
+GeoDjango's lookup types may be used with any manager method like
+``filter()``, ``exclude()``, etc. However, the lookup types unique to
+GeoDjango are only available on geometry fields.
+Filters on 'normal' fields (e.g. :class:`~django.db.models.CharField`)
+may be chained with those on geographic fields. Thus, geographic queries
+take the following general form (assuming the ``Zipcode`` model used in the
+:ref:`ref-gis-model-api`)::
+
+ >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
+ >>> qs = Zipcode.objects.exclude(...)
+
+For example::
+
+ >>> qs = Zipcode.objects.filter(poly__contains=pnt)
+
+In this case, ``poly`` is the geographic field, :lookup:`contains <gis-contains>`
+is the spatial lookup type, and ``pnt`` is the parameter (which may be a
+:class:`~django.contrib.gis.geos.GEOSGeometry` object or a string of
+GeoJSON , WKT, or HEXEWKB).
+
+A complete reference can be found in the :ref:`spatial lookup reference
+<spatial-lookups>`.
+
+.. note::
+
+ GeoDjango constructs spatial SQL with the :class:`GeoQuerySet`, a
+ subclass of :class:`~django.db.models.QuerySet`. The
+ :class:`GeoManager` instance attached to your model is what
+ enables use of :class:`GeoQuerySet`.
+
+.. _distance-queries:
+
+Distance Queries
+================
+
+Introduction
+------------
+Distance calculations with spatial data is tricky because, unfortunately,
+the Earth is not flat. Some distance queries with fields in a geographic
+coordinate system may have to be expressed differently because of
+limitations in PostGIS. Please see the :ref:`selecting-an-srid` section
+in the :ref:`ref-gis-model-api` documentation for more details.
+
+.. _distance-lookups-intro:
+
+Distance Lookups
+----------------
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+The following distance lookups are available:
+
+* :lookup:`distance_lt`
+* :lookup:`distance_lte`
+* :lookup:`distance_gt`
+* :lookup:`distance_gte`
+* :lookup:`dwithin`
+
+.. note::
+
+ For *measuring*, rather than querying on distances, use the
+ :meth:`GeoQuerySet.distance` method.
+
+Distance lookups take a tuple parameter comprising:
+
+#. A geometry to base calculations from; and
+#. A number or :class:`~django.contrib.gis.measure.Distance` object containing the distance.
+
+If a :class:`~django.contrib.gis.measure.Distance` object is used,
+it may be expressed in any units (the SQL generated will use units
+converted to those of the field); otherwise, numeric parameters are assumed
+to be in the units of the field.
+
+.. note::
+
+ For PostGIS users, the routine ``ST_distance_sphere``
+ is used by default for calculating distances on geographic coordinate systems
+ -- which may only be called with point geometries [#fndistsphere]_. Thus,
+ geographic distance lookups on traditional PostGIS geometry columns are
+ only allowed on :class:`PointField` model fields using a point for the
+ geometry parameter.
+
+.. note::
+
+ PostGIS 1.5 introduced :ref:`geography columns <geography-type>`, which
+ is limited on what geometry types distance queries are performed with. In
+ other words, if you have ``geography=True`` in your geometry field
+ definition you'll be allowed to peform arbitrary distance queries with your
+ data in geodetic units of WGS84.
+
+
+For example, let's say we have a ``SouthTexasCity`` model (from the
+`GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities
+in southern Texas::
+
+ from django.contrib.gis.db import models
+
+ class SouthTexasCity(models.Model):
+ name = models.CharField(max_length=30)
+ # A projected coordinate system (only valid for South Texas!)
+ # is used, units are in meters.
+ point = models.PointField(srid=32140)
+ objects = models.GeoManager()
+
+Then distance queries may be performed as follows::
+
+ >>> from django.contrib.gis.geos import *
+ >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
+ >>> from geoapp import SouthTexasCity
+ # Distances will be calculated from this point, which does not have to be projected.
+ >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
+ # If numeric parameter, units of field (meters in this case) are assumed.
+ >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
+ # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
+ >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
+ >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
+ >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
+
+__ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
+
+.. _compatibility-table:
+
+Compatibility Tables
+====================
+
+.. _spatial-lookup-compatibility:
+
+Spatial Lookups
+---------------
+
+The following table provides a summary of what spatial lookups are available
+for each spatial database backend.
+
+================================= ========= ======== ============ ==========
+Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite
+================================= ========= ======== ============ ==========
+:lookup:`bbcontains` X X X
+:lookup:`bboverlaps` X X X
+:lookup:`contained` X X X
+:lookup:`contains <gis-contains>` X X X X
+:lookup:`contains_properly` X
+:lookup:`coveredby` X X
+:lookup:`covers` X X
+:lookup:`crosses` X X
+:lookup:`disjoint` X X X X
+:lookup:`distance_gt` X X X
+:lookup:`distance_gte` X X X
+:lookup:`distance_lt` X X X
+:lookup:`distance_lte` X X X
+:lookup:`dwithin` X X
+:lookup:`equals` X X X X
+:lookup:`exact` X X X X
+:lookup:`intersects` X X X X
+:lookup:`overlaps` X X X X
+:lookup:`relate` X X X
+:lookup:`same_as` X X X X
+:lookup:`touches` X X X X
+:lookup:`within` X X X X
+:lookup:`left` X
+:lookup:`right` X
+:lookup:`overlaps_left` X
+:lookup:`overlaps_right` X
+:lookup:`overlaps_above` X
+:lookup:`overlaps_below` X
+:lookup:`strictly_above` X
+:lookup:`strictly_below` X
+================================= ========= ======== ============ ==========
+
+.. _geoqueryset-method-compatibility:
+
+``GeoQuerySet`` Methods
+-----------------------
+The following table provides a summary of what :class:`GeoQuerySet` methods
+are available on each spatial backend. Please note that MySQL does not
+support any of these methods, and is thus excluded from the table.
+
+==================================== ======= ====== ==========
+Method PostGIS Oracle SpatiaLite
+==================================== ======= ====== ==========
+:meth:`GeoQuerySet.area` X X X
+:meth:`GeoQuerySet.centroid` X X X
+:meth:`GeoQuerySet.collect` X
+:meth:`GeoQuerySet.difference` X X X
+:meth:`GeoQuerySet.distance` X X X
+:meth:`GeoQuerySet.envelope` X X
+:meth:`GeoQuerySet.extent` X X
+:meth:`GeoQuerySet.extent3d` X
+:meth:`GeoQuerySet.force_rhr` X
+:meth:`GeoQuerySet.geohash` X
+:meth:`GeoQuerySet.geojson` X
+:meth:`GeoQuerySet.gml` X X
+:meth:`GeoQuerySet.intersection` X X X
+:meth:`GeoQuerySet.kml` X
+:meth:`GeoQuerySet.length` X X X
+:meth:`GeoQuerySet.make_line` X
+:meth:`GeoQuerySet.mem_size` X
+:meth:`GeoQuerySet.num_geom` X X X
+:meth:`GeoQuerySet.num_points` X X X
+:meth:`GeoQuerySet.perimeter` X X
+:meth:`GeoQuerySet.point_on_surface` X X X
+:meth:`GeoQuerySet.reverse_geom` X X
+:meth:`GeoQuerySet.scale` X X
+:meth:`GeoQuerySet.snap_to_grid` X
+:meth:`GeoQuerySet.svg` X X
+:meth:`GeoQuerySet.sym_difference` X X X
+:meth:`GeoQuerySet.transform` X X X
+:meth:`GeoQuerySet.translate` X X
+:meth:`GeoQuerySet.union` X X X
+:meth:`GeoQuerySet.unionagg` X X X
+==================================== ======= ====== ==========
+
+.. rubric:: Footnotes
+.. [#fnwkt] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
+.. [#fnewkb] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#EWKB_EWKT>`_, PostGIS documentation at Ch. 4.1.2.
+.. [#fngeojson] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008).
+.. [#fndistsphere] *See* PostGIS 1.5 ``ST_distance_sphere`` `documentation <http://postgis.refractions.net/documentation/manual-1.5/ST_Distance_Sphere.html>`_.
+.. [#] MySQL only supports bounding box operations (known as minimum bounding rectangles, or MBR, in MySQL). Thus, spatial lookups such as :lookup:`contains <gis-contains>` are really equivalent to :lookup:`bbcontains`.
View
99 docs/ref/contrib/gis/deployment.txt
@@ -0,0 +1,99 @@
+===================
+Deploying GeoDjango
+===================
+
+.. warning::
+
+ GeoDjango uses the GDAL geospatial library which is
+ not thread safe at this time. Thus, it is *highly* recommended
+ to not use threading when deploying -- in other words, use a
+ an appropriate configuration of Apache or the prefork method
+ when using FastCGI through another web server.
+
+Apache
+======
+In this section there are some example ``VirtualHost`` directives for
+when deploying using either ``mod_python`` or ``mod_wsgi``. At this
+time, we recommend ``mod_wsgi``, as it is now officially recommended
+way to deploy Django applications with Apache. Moreover, if
+``mod_python`` is used, then a prefork version of Apache must also be
+used. As long as ``mod_wsgi`` is configured correctly, it does not
+matter whether the version of Apache is prefork or worker.
+
+.. note::
+
+ The ``Alias`` and ``Directory`` configurations in the the examples
+ below use an example path to a system-wide installation folder of Django.
+ Substitute in an appropriate location, if necessary, as it may be
+ different than the path on your system.
+
+``mod_wsgi``
+------------
+
+Example::
+
+ <VirtualHost *:80>
+ WSGIDaemonProcess geodjango user=geo group=geo processes=5 threads=1
+ WSGIProcessGroup geodjango
+ WSGIScriptAlias / /home/geo/geodjango/world.wsgi
+
+ Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
+ <Directory "/usr/lib/python2.5/site-packages/django/contrib/admin/media/">
+ Order allow,deny
+ Options Indexes
+ Allow from all
+ IndexOptions FancyIndexing
+ </Directory>
+
+ </VirtualHost>
+
+.. warning::
+
+ If the ``WSGIDaemonProcess`` attribute ``threads`` is not set to ``1``, then
+ Apache may crash when running your GeoDjango application. Increase the
+ number of ``processes`` instead.
+
+For more information, please consult Django's
+:ref:`mod_wsgi documentation <howto-deployment-modwsgi>`.
+
+``mod_python``
+--------------
+
+Example::
+
+ <VirtualHost *:80>
+
+ <Location "/">
+ SetHandler mod_python
+ PythonHandler django.core.handlers.modpython
+ SetEnv DJANGO_SETTINGS_MODULE world.settings
+ PythonDebug On
+ PythonPath "['/var/www/apps'] + sys.path"
+ </Location>
+
+ Alias /media/ "/usr/lib/python2.5/site-packages/django/contrib/admin/media/"
+ <Location "/media">
+ SetHandler None
+ </Location>
+
+ </VirtualHost>
+
+.. warning::
+
+ When using ``mod_python`` you *must* be using a prefork version of Apache, or
+ else your GeoDjango application may crash Apache.
+
+For more information, please consult Django's
+:ref:`mod_python documentation <howto-deployment-modpython>`.
+
+Lighttpd
+========
+
+FastCGI
+-------
+
+Nginx
+=====
+
+FastCGI
+-------
View
97 docs/ref/contrib/gis/feeds.txt
@@ -0,0 +1,97 @@
+.. _ref-gis-feeds:
+
+================
+Geographic Feeds
+================
+
+.. module:: django.contrib.gis.feeds
+ :synopsis: GeoDjango's framework for generating spatial feeds.
+
+GeoDjango has its own :class:`Feed` subclass that may embed location information
+in RSS/Atom feeds formatted according to either the `Simple GeoRSS`__ or
+`W3C Geo`_ standards. Because GeoDjango's syndication API is a superset of
+Django's, please consult `Django's syndication documentation <ref-contrib-syndication>`
+for details on general usage.
+
+.. _W3C Geo: http://www.w3.org/2003/01/geo/
+
+__ http://georss.org/1.0#simple
+
+Example
+=======
+
+API Reference
+=============
+
+``Feed`` Subclass
+-----------------
+
+.. class:: Feed
+
+ In addition to methods provided by
+ the :class:`django.contrib.syndication.feeds.Feed`
+ base class, GeoDjango's ``Feed`` class provides
+ the following overrides. Note that these overrides may be done in multiple ways::
+
+ from django.contrib.gis.feeds import Feed
+
+ class MyFeed(Feed):
+
+ # First, as a class attribute.
+ geometry = ...
+ item_geometry = ...
+
+ # Also a function with no arguments
+ def geometry(self):
+ ...
+
+ def item_geometry(self):
+ ...
+
+ # And as a function with a single argument
+ def geometry(self, obj):
+ ...
+
+ def item_geometry(self, item):
+ ...
+
+ .. method:: geometry(obj)
+
+ Takes the object returned by ``get_object()`` and returns the *feed's*
+ geometry. Typically this is a ``GEOSGeometry`` instance, or can be a
+ tuple to represent a point or a box. For example::
+
+ class ZipcodeFeed(Feed):
+
+ def geometry(self, obj):
+ # Can also return: `obj.poly`, and `obj.poly.centroid`.
+ return obj.poly.extent # tuple like: (X0, Y0, X1, Y1).
+
+ .. method:: item_geometry(item)
+
+ Set this to return the geometry for each *item* in the feed. This
+ can be a ``GEOSGeometry`` instance, or a tuple that represents a
+ point coordinate or bounding box. For example::
+
+ class ZipcodeFeed(Feed):
+
+ def item_geometry(self, obj):
+ # Returns the polygon.
+ return obj.poly
+
+``SyndicationFeed`` Subclasses
+------------------------------
+
+The following :class:`django.utils.feedgenerator.SyndicationFeed` subclasses
+are available:
+
+.. class:: GeoRSSFeed
+
+.. class:: GeoAtom1Feed
+
+.. class:: W3CGeoFeed
+
+.. note::
+
+ `W3C Geo`_ formatted feeds only support
+ :class:`~django.contrib.gis.db.models.PointField` geometries.
View
1,114 docs/ref/contrib/gis/gdal.txt
@@ -0,0 +1,1114 @@
+.. _ref-gdal:
+
+========
+GDAL API
+========
+
+.. module:: django.contrib.gis.gdal
+ :synopsis: GeoDjango's high-level interface to the GDAL library.
+
+`GDAL`__ stands for **G**\ eospatial **D**\ ata **A**\ bstraction **L**\ ibrary,
+and is a veritable "swiss army knife" of GIS data functionality. A subset
+of GDAL is the `OGR`__ Simple Features Library, which specializes
+in reading and writing vector geographic data in a variety of standard
+formats.
+
+GeoDjango provides a high-level Python interface for some of the
+capabilities of OGR, including the reading and coordinate transformation
+of vector spatial data.
+
+.. note::
+
+ Although the module is named ``gdal``, GeoDjango only supports
+ some of the capabilities of OGR. Thus, none of GDAL's features
+ with respect to raster (image) data are supported at this time.
+
+__ http://www.gdal.org/
+__ http://www.gdal.org/ogr/
+
+Overview
+========
+
+Sample Data
+-----------
+
+The GDAL/OGR tools described here are designed to help you read in
+your geospatial data, in order for most of them to be useful you have
+to have some data to work with. If you're starting out and don't yet
+have any data of your own to use, GeoDjango comes with a number of
+simple data sets that you can use for testing. This snippet will
+determine where these sample files are installed on your computer::
+
+ >>> import os
+ >>> import django.contrib.gis
+ >>> GIS_PATH = os.path.dirname(django.contrib.gis.__file__)
+ >>> CITIES_PATH = os.path.join(GIS_PATH, 'tests/data/cities/cities.shp')
+
+Vector Data Source Objects
+==========================
+
+``DataSource``
+--------------
+
+:class:`DataSource` is a wrapper for the OGR data source object that
+supports reading data from a variety of OGR-supported geospatial file
+formats and data sources using a simple, consistent interface. Each
+data source is represented by a :class:`DataSource` object which contains
+one or more layers of data. Each layer, represented by a :class:`Layer`
+object, contains some number of geographic features (:class:`Feature`),
+information about the type of features contained in that layer (e.g.
+points, polygons, etc.), as well as the names and types of any
+additional fields (:class:`Field`) of data that may be associated with
+each feature in that layer.
+
+.. class:: DataSource(ds_input)
+
+ The constructor for ``DataSource`` just a single parameter: the path of
+ the file you want to read. However, OGR
+ also supports a variety of more complex data sources, including
+ databases, that may be accessed by passing a special name string instead
+ of a path. For more information, see the `OGR Vector Formats`__
+ documentation. The :attr:`name` property of a ``DataSource``
+ instance gives the OGR name of the underlying data source that it is
+ using.
+
+ Once you've created your ``DataSource``, you can find out how many
+ layers of data it contains by accessing the :attr:`layer_count` property,
+ or (equivalently) by using the ``len()`` function. For information on
+ accessing the layers of data themselves, see the next section::
+
+ >>> from django.contrib.gis.gdal import DataSource
+ >>> ds = DataSource(CITIES_PATH)
+ >>> ds.name # The exact filename may be different on your computer
+ '/usr/local/lib/python2.6/site-packages/django/contrib/gis/tests/data/cities/cities.shp'
+ >>> ds.layer_count # This file only contains one layer
+ 1
+
+ .. attribute:: layer_count
+
+ Returns the number of layers in the data source.
+
+ .. attribute:: name
+
+ Returns the name of the data source.
+
+__ http://www.gdal.org/ogr/ogr_formats.html
+
+``Layer``
+---------
+
+.. class:: Layer
+
+ ``Layer`` is a wrapper for a layer of data in a ``DataSource`` object.
+ You never create a ``Layer`` object directly. Instead, you retrieve
+ them from a :class:`DataSource` object, which is essentially a standard
+ Python container of ``Layer`` objects. For example, you can access a
+ specific layer by its index (e.g. ``ds[0]`` to access the first
+ layer), or you can iterate over all the layers in the container in a
+ ``for`` loop. The ``Layer`` itself acts as a container for geometric
+ features.
+
+ Typically, all the features in a given layer have the same geometry type.
+ The :attr:`geom_type` property of a layer is an :class:`OGRGeomType`
+ that identifies the feature type. We can use it to print out some basic
+ information about each layer in a :class:`DataSource`::
+
+ >>> for layer in ds:
+ ... print 'Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name)
+ ...
+ Layer "cities": 3 Points
+
+ The example output is from the cities data source, loaded above, which
+ evidently contains one layer, called ``"cities"``, which contains three
+ point features. For simplicity, the examples below assume that you've
+ stored that layer in the variable ``layer``::
+
+ >>> layer = ds[0]
+
+ .. attribute:: name
+
+ Returns the name of this layer in the data source.
+
+ >>> layer.name
+ 'cities'
+
+ .. attribute:: num_feat
+
+ Returns the number of features in the layer. Same as ``len(layer)``::
+
+ >>> layer.num_feat
+ 3
+
+ .. attribute:: geom_type
+
+ Returns the geometry type of the layer, as an :class:`OGRGeomType`
+ object::
+
+ >>> layer.geom_type.name
+ 'Point'
+
+ .. attribute:: num_fields
+
+ Returns the number of fields in the layer, i.e the number of fields of
+ data associated with each feature in the layer::
+
+ >>> layer.num_fields
+ 4
+
+ .. attribute:: fields
+
+ Returns a list of the names of each of the fields in this layer::
+
+ >>> layer.fields
+ ['Name', 'Population', 'Density', 'Created']
+
+ .. attribute field_types
+
+ Returns a list of the data types of each of the fields in this layer.
+ These are subclasses of ``Field``, discussed below::
+
+ >>> [ft.__name__ for ft in layer.field_types]
+ ['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']
+
+ .. attribute:: field_widths
+
+ Returns a list of the maximum field widths for each of the fields in
+ this layer::
+
+ >>> layer.field_widths
+ [80, 11, 24, 10]
+
+ .. attribute:: field_precisions
+
+ Returns a list of the numeric precisions for each of the fields in
+ this layer. This is meaningless (and set to zero) for non-numeric
+ fields::
+
+ >>> layer.field_precisions
+ [0, 0, 15, 0]
+
+ .. attribute:: extent
+
+ Returns the spatial extent of this layer, as an :class:`Envelope`
+ object::
+
+ >>> layer.extent.tuple
+ (-104.609252, 29.763374, -95.23506, 38.971823)
+
+ .. attribute:: srs
+
+ Property that returns the :class:`SpatialReference` associated
+ with this layer::
+
+ >>> print layer.srs
+ GEOGCS["GCS_WGS_1984",
+ DATUM["WGS_1984",
+ SPHEROID["WGS_1984",6378137,298.257223563]],
+ PRIMEM["Greenwich",0],
+ UNIT["Degree",0.017453292519943295]]
+
+ If the :class:`Layer` has no spatial reference information associated
+ with it, ``None`` is returned.
+
+ .. attribute:: spatial_filter
+
+ .. versionadded:: 1.2
+
+ Property that may be used to retrieve or set a spatial filter for this
+ layer. A spatial filter can only be set with an :class:`OGRGeometry`
+ instance, a 4-tuple extent, or ``None``. When set with something
+ other than ``None``, only features that intersect the filter will be
+ returned when iterating over the layer::
+
+ >>> print layer.spatial_filter
+ None
+ >>> print len(layer)
+ 3
+ >>> [feat.get('Name') for feat in layer]
+ ['Pueblo', 'Lawrence', 'Houston']
+ >>> ks_extent = (-102.051, 36.99, -94.59, 40.00) # Extent for state of Kansas
+ >>> layer.spatial_filter = ks_extent
+ >>> len(layer)
+ 1
+ >>> [feat.get('Name') for feat in layer]
+ ['Lawrence']
+ >>> layer.spatial_filter = None
+ >>> len(layer)
+ 3
+
+ .. method:: get_fields()
+
+ A method that returns a list of the values of a given field for each
+ feature in the layer::
+
+ >>> layer.get_fields('Name')
+ ['Pueblo', 'Lawrence', 'Houston']
+
+ .. method:: get_geoms([geos=False])
+
+ A method that returns a list containing the geometry of each feature
+ in the layer. If the optional argument ``geos`` is set to ``True``
+ then the geometries are converted to :class:`~django.contrib.gis.geos.GEOSGeometry`
+ objects. Otherwise, they are returned as :class:`OGRGeometry` objects::
+
+ >>> [pt.tuple for pt in layer.get_geoms()]
+ [(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]
+
+ .. method:: test_capability(capability)
+
+ Returns a boolean indicating whether this layer supports the
+ given capability (a string). Examples of valid capability strings
+ include: ``'RandomRead'``, ``'SequentialWrite'``, ``'RandomWrite'``,
+ ``'FastSpatialFilter'``, ``'FastFeatureCount'``, ``'FastGetExtent'``,
+ ``'CreateField'``, ``'Transactions'``, ``'DeleteFeature'``, and
+ ``'FastSetNextByIndex'``.
+
+``Feature``
+-----------
+
+.. class:: Feature
+
+
+ ``Feature`` wraps an OGR feature. You never create a ``Feature``
+ object directly. Instead, you retrieve them from a :class:`Layer` object.
+ Each feature consists of a geometry and a set of fields containing
+ additional properties. The geometry of a field is accessible via its
+ ``geom`` property, which returns an :class:`OGRGeometry` object. A ``Feature``
+ behaves like a standard Python container for its fields, which it returns as
+ :class:`Field` objects: you can access a field directly by its index or name,
+ or you can iterate over a feature's fields, e.g. in a ``for`` loop.
+
+ .. attribute:: geom
+
+ Returns the geometry for this feature, as an ``OGRGeometry`` object::
+
+ >>> city.geom.tuple
+ (-104.609252, 38.255001)
+
+ .. attribute:: get
+
+ A method that returns the value of the given field (specified by name)
+ for this feature, **not** a ``Field`` wrapper object::
+
+ >>> city.get('Population')
+ 102121
+
+ .. attribute:: geom_type
+
+ Returns the type of geometry for this feature, as an :class:`OGRGeomType`
+ object. This will be the same for all features in a given layer, and
+ is equivalent to the :attr:`Layer.geom_type` property of the
+ :class:`Layer`` object the feature came from.
+
+ .. attribute:: num_fields
+
+ Returns the number of fields of data associated with the feature.
+ This will be the same for all features in a given layer, and is
+ equivalent to the :attr:`Layer.num_fields` property of the
+ :class:`Layer` object the feature came from.
+
+ .. attribute:: fields
+
+ Returns a list of the names of the fields of data associated with the
+ feature. This will be the same for all features in a given layer, and
+ is equivalent to the :attr:`Layer.fields` property of the :class:`Layer`
+ object the feature came from.
+
+ .. attribute:: fid
+
+ Returns the feature identifier within the layer::
+
+ >>> city.fid
+ 0
+
+ .. attribute:: layer_name
+
+ Returns the name of the :class:`Layer` that the feature came from.
+ This will be the same for all features in a given layer::
+
+ >>> city.layer_name
+ 'cities'
+
+ .. attribute:: index
+
+ A method that returns the index of the given field name. This will be
+ the same for all features in a given layer::
+
+ >>> city.index('Population')
+ 1
+
+``Field``
+---------
+
+.. class:: Field
+
+ .. attribute:: name
+
+ Returns the name of this field::
+
+ >>> city['Name'].name
+ 'Name'
+
+ .. attribute:: type
+
+ Returns the OGR type of this field, as an integer. The
+ ``FIELD_CLASSES`` dictionary maps these values onto
+ subclasses of ``Field``::
+
+ >>> city['Density'].type
+ 2
+
+ .. attribute:: type_name
+
+ Returns a string with the name of the data type of this field::
+
+ >>> city['Name'].type_name
+ 'String'
+
+ .. attribute:: value
+
+ Returns the value of this field. The ``Field`` class itself
+ returns the value as a string, but each subclass returns the
+ value in the most appropriate form::
+
+ >>> city['Population'].value
+ 102121
+
+ .. attribute:: width
+
+ Returns the width of this field::
+
+ >>> city['Name'].width
+ 80
+
+ .. attribute:: precision
+
+ Returns the numeric precision of this field. This is meaningless (and
+ set to zero) for non-numeric fields::
+
+ >>> city['Density'].precision
+ 15
+
+ .. method:: as_double()
+
+ Returns the value of the field as a double (float)::
+
+ >>> city['Density'].as_double()
+ 874.7
+
+ .. method:: as_int()
+
+ Returns the value of the field as an integer::
+
+ >>> city['Population'].as_int()
+ 102121
+
+ .. method:: as_string()
+
+ Returns the value of the field as a string::
+
+ >>> city['Name'].as_string()
+ 'Pueblo'
+
+ .. method:: as_datetime()
+
+ Returns the value of the field as a tuple of date and time components::
+
+ >>> city['Created'].as_datetime()
+ (c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))
+
+``Driver``
+----------
+
+.. class:: Driver(dr_input)
+
+ The ``Driver`` class is used internally to wrap an OGR :class:`DataSource` driver.
+
+ .. attribute:: driver_count
+
+ Returns the number of OGR vector drivers currently registered.
+
+
+OGR Geometries
+==============
+
+``OGRGeometry``
+---------------
+
+:class:`OGRGeometry` objects share similar functionality with
+:class:`~django.contrib.gis.geos.GEOSGeometry` objects, and are thin
+wrappers around OGR's internal geometry representation. Thus,
+they allow for more efficient access to data when using :class:`DataSource`.
+Unlike its GEOS counterpart, :class:`OGRGeometry` supports spatial reference
+systems and coordinate transformation::
+
+ >>> from django.contrib.gis.gdal import OGRGeometry
+ >>> polygon = OGRGeometry('POLYGON((0 0, 5 0, 5 5, 0 5))')
+
+.. class:: OGRGeometry(geom_input[, srs=None])
+
+ This object is a wrapper for the `OGR Geometry`__ class.
+ These objects are instantiated directly from the given ``geom_input``
+ parameter, which may be a string containing WKT or HEX, a ``buffer``
+ containing WKB data, or an :class:`OGRGeomType` object. These objects
+ are also returned from the :class:`Feature.geom` attribute, when
+ reading vector data from :class:`Layer` (which is in turn a part of
+ a :class:`DataSource`).
+
+ __ http://www.gdal.org/ogr/classOGRGeometry.html
+
+ .. classmethod:: from_bbox(bbox)
+
+ .. versionadded:: 1.1
+
+ Constructs a :class:`Polygon` from the given bounding-box (a 4-tuple).
+
+ .. method:: __len__
+
+ Returns the number of points in a :class:`LineString`, the
+ number of rings in a :class:`Polygon`, or the number of geometries in a
+ :class:`GeometryCollection`. Not applicable to other geometry types.
+
+ .. method:: __iter__
+
+ Iterates over the points in a :class:`LineString`, the rings in a
+ :class:`Polygon`, or the geometries in a :class:`GeometryCollection`.
+ Not applicable to other geometry types.
+
+ .. method:: __getitem__
+
+ Returns the point at the specified index for a :class:`LineString`, the
+ interior ring at the specified index for a :class:`Polygon`, or the geometry
+ at the specified index in a :class:`GeometryCollection`. Not applicable to
+ other geometry types.
+
+ .. attribute:: dimension
+
+ Returns the number of coordinated dimensions of the geometry, i.e. 0
+ for points, 1 for lines, and so forth::
+
+ >> polygon.dimension
+ 2
+
+ .. attribute:: coord_dim
+
+ .. versionchanged:: 1.2
+
+ Returns or sets the coordinate dimension of this geometry. For
+ example, the value would be 2 for two-dimensional geometries.
+
+ .. note::
+
+ Setting this property is only available in versions 1.2 and above.
+
+ .. attribute:: geom_count
+
+ Returns the number of elements in this geometry::
+
+ >>> polygon.geom_count
+ 1
+
+ .. attribute:: point_count
+
+ Returns the number of points used to describe this geometry::
+
+ >>> polygon.point_count
+ 4
+
+ .. attribute:: num_points
+
+ Alias for :attr:`point_count`.
+
+ .. attribute:: num_coords
+
+ Alias for :attr:`point_count`.
+
+ .. attribute:: geom_type
+
+ Returns the type of this geometry, as an :class:`OGRGeomType` object.
+
+ .. attribute:: geom_name
+
+ Returns the name of the type of this geometry::
+
+ >>> polygon.geom_name
+ 'POLYGON'
+
+ .. attribute:: area
+
+ Returns the area of this geometry, or 0 for geometries that do not
+ contain an area::
+
+ >>> polygon.area
+ 25.0
+
+ .. attribute:: envelope
+
+ Returns the envelope of this geometry, as an :class:`Envelope` object.
+
+ .. attribute:: extent
+
+ Returns the envelope of this geometry as a 4-tuple, instead of as an
+ :class:`Envelope` object::
+
+ >>> point.extent
+ (0.0, 0.0, 5.0, 5.0)
+
+ .. attribute:: srs
+
+ This property controls the spatial reference for this geometry, or
+ ``None`` if no spatial reference system has been assigned to it.
+ If assigned, accessing this property returns a :class:`SpatialReference`
+ object. It may be set with another :class:`SpatialReference` object,
+ or any input that :class:`SpatialReference` accepts. Example::
+
+ >>> city.geom.srs.name
+ 'GCS_WGS_1984'
+
+ .. attribute:: srid
+
+ Returns or sets the spatial reference identifier corresponding to
+ :class:`SpatialReference` of this geometry. Returns ``None`` if
+ there is no spatial reference information associated with this
+ geometry, or if an SRID cannot be determined.
+
+ .. attribute:: geos
+
+ Returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object
+ corresponding to this geometry.
+
+ .. attribute:: gml
+
+ Returns a string representation of this geometry in GML format::
+
+ >>> OGRGeometry('POINT(1 2)').gml
+ '<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'
+
+ .. attribute:: hex
+
+ Returns a string representation of this geometry in HEX WKB format::
+
+ >>> OGRGeometry('POINT(1 2)').hex
+ '0101000000000000000000F03F0000000000000040'
+
+ .. attribute:: json
+
+ Returns a string representation of this geometry in JSON format::
+
+ >>> OGRGeometry('POINT(1 2)').json
+ '{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'
+
+
+ .. attribute:: kml
+
+ .. versionadded:: 1.1
+
+ Returns a string representation of this geometry in KML format.
+
+ .. attribute:: wkb_size
+
+ Returns the size of the WKB buffer needed to hold a WKB representation
+ of this geometry::
+
+ >>> OGRGeometry('POINT(1 2)').wkb_size
+ 21
+
+ .. attribute:: wkb
+
+ Returns a ``buffer`` containing a WKB representation of this geometry.
+
+ .. attribute:: wkt
+
+ Returns a string representation of this geometry in WKT format.
+
+ .. attribute:: ewkt
+
+ .. versionadded:: 1.2
+
+ Returns the EWKT representation of this geometry.
+
+ .. method:: clone()
+
+ Returns a new :class:`OGRGeometry` clone of this geometry object.
+
+ .. method:: close_rings()
+
+ If there are any rings within this geometry that have not been closed,
+ this routine will do so by adding the starting point to the end::
+
+ >>> triangle = OGRGeometry('LINEARRING (0 0,0 1,1 0)')
+ >>> triangle.close_rings()
+ >>> triangle.wkt
+ 'LINEARRING (0 0,0 1,1 0,0 0)'
+
+ .. method:: transform(coord_trans, clone=False)
+
+ Transforms this geometry to a different spatial reference system. May
+ take a :class:`CoordTransform` object, a :class:`SpatialReference` object,
+ or any other input accepted by :class:`SpatialReference` (including
+ spatial reference WKT and PROJ.4 strings, or an integer SRID).
+ By default nothing is returned and the geometry is transformed in-place.
+ However, if the `clone` keyword is set to ``True`` then a transformed clone
+ of this geometry is returned instead.
+
+ .. method:: intersects(other)
+
+ Returns ``True`` if this geometry intersects the other, otherwise returns
+ ``False``.
+
+ .. method:: equals(other)
+
+ Returns ``True`` if this geometry is equivalent to the other, otherwise returns
+ ``False``.
+
+ .. method:: disjoint(other)
+
+ Returns ``True`` if this geometry is spatially disjoint to (i.e. does
+ not intersect) the other, otherwise returns ``False``.
+
+ .. method:: touches(other)
+
+ Returns ``True`` if this geometry touches the other, otherwise returns
+ ``False``.
+
+ .. method:: crosses(other)
+
+ Returns ``True`` if this geometry crosses the other, otherwise returns
+ ``False``.
+
+ .. method:: within(other)
+
+ Returns ``True`` if this geometry is contained within the other, otherwise returns
+ ``False``.
+
+ .. method:: contains(other)
+
+ Returns ``True`` if this geometry contains the other, otherwise returns
+ ``False``.
+
+ .. method:: overlaps(other)
+
+ Returns ``True`` if this geometry overlaps the other, otherwise returns
+ ``False``.
+
+ .. method:: boundary
+
+ The boundary of this geometry, as a new :class:`OGRGeometry` object.
+
+ .. attribute:: convex_hull
+
+ The smallest convex polygon that contains this geometry, as a new
+ :class:`OGRGeometry` object.
+
+ .. method:: difference
+
+ Returns the region consisting of the difference of this geometry and
+ the other, as a new :class:`OGRGeometry` object.
+
+ .. method:: intersection
+
+ Returns the region consisting of the intersection of this geometry and
+ the other, as a new :class:`OGRGeometry` object.
+
+ .. method:: sym_difference
+
+ Returns the region consisting of the symmetric difference of this
+ geometry and the other, as a new :class:`OGRGeometry` object.
+
+ .. method:: union
+
+ Returns the region consisting of the union of this geometry and
+ the other, as a new :class:`OGRGeometry` object.
+
+ .. attribute:: tuple
+
+ Returns the coordinates of a point geometry as a tuple, the
+ coordinates of a line geometry as a tuple of tuples, and so forth::
+
+ >>> OGRGeometry('POINT (1 2)').tuple
+ (1.0, 2.0)
+ >>> OGRGeometry('LINESTRING (1 2,3 4)').tuple
+ ((1.0, 2.0), (3.0, 4.0))
+
+ .. attribute:: coords
+
+ An alias for :attr:`tuple`.
+
+.. class:: Point
+
+ .. attribute:: x
+
+ Returns the X coordinate of this point::
+
+ >>> OGRGeometry('POINT (1 2)').x
+ 1.0
+
+ .. attribute:: y
+
+ Returns the Y coordinate of this point::
+
+ >>> OGRGeometry('POINT (1 2)').y
+ 2.0
+
+ .. attribute:: z
+
+ Returns the Z coordinate of this point, or ``None`` if the
+ the point does not have a Z coordinate::
+
+ >>> OGRGeometry('POINT (1 2 3)').z
+ 3.0
+
+.. class:: LineString
+
+ .. attribute:: x
+
+ Returns a list of X coordinates in this line::
+
+ >>> OGRGeometry('LINESTRING (1 2,3 4)').x
+ [1.0, 3.0]
+
+ .. attribute:: y
+
+ Returns a list of Y coordinates in this line::
+
+ >>> OGRGeometry('LINESTRING (1 2,3 4)').y
+ [2.0, 4.0]
+
+ .. attribute:: z
+
+ Returns a list of Z coordinates in this line, or ``None`` if the
+ line does not have Z coordinates::
+
+ >>> OGRGeometry('LINESTRING (1 2 3,4 5 6)').z
+ [3.0, 6.0]
+
+
+.. class:: Polygon
+
+ .. attribute:: shell
+
+ Returns the shell or exterior ring of this polygon, as a ``LinearRing``
+ geometry.
+
+ .. attribute:: exterior_ring
+
+ An alias for :attr:`shell`.
+
+ .. attribute:: centroid
+
+ Returns a :class:`Point` representing the centroid of this polygon.
+
+.. class:: GeometryCollection
+
+ .. method:: add(geom)
+
+ Adds a geometry to this geometry collection. Not applicable to other
+ geometry types.
+
+
+``OGRGeomType``
+---------------
+
+.. class:: OGRGeomType(type_input)
+
+ This class allows for the representation of an OGR geometry type
+ in any of several ways::
+
+ >>> from django.contrib.gis.gdal import OGRGeomType
+ >>> gt1 = OGRGeomType(3) # Using an integer for the type
+ >>> gt2 = OGRGeomType('Polygon') # Using a string
+ >>> gt3 = OGRGeomType('POLYGON') # It's case-insensitive
+ >>> print gt1 == 3, gt1 == 'Polygon' # Equivalence works w/non-OGRGeomType objects
+ True True
+
+ .. attribute:: name
+
+ Returns a short-hand string form of the OGR Geometry type::
+
+ >>> gt1.name
+ 'Polygon'
+
+ .. attribute:: num
+
+ Returns the number corresponding to the OGR geometry type::
+
+ >>> gt1.num
+ 3
+
+ .. attribute:: django
+
+ Returns the Django field type (a subclass of GeometryField) to use for
+ storing this OGR type, or ``None`` if there is no appropriate Django
+ type::
+
+ >>> gt1.django
+ 'PolygonField'
+
+``Envelope``
+------------
+
+.. class:: Envelope(*args)
+
+ Represents an OGR Envelope structure that contains the
+ minimum and maximum X, Y coordinates for a rectangle bounding box.
+ The naming of the variables is compatible with the OGR Envelope
+ C structure.
+
+ .. attribute:: min_x
+
+ The value of the minimum X coordinate.
+
+ .. attribute:: min_y
+
+ The value of the maximum X coordinate.
+
+ .. attribute:: max_x
+
+ The value of the minimum Y coordinate.
+
+ .. attribute:: max_y
+
+ The value of the maximum Y coordinate.
+
+ .. attribute:: ur
+
+ The upper-right coordinate, as a tuple.
+
+ .. attribute:: ll
+
+ The lower-left coordinate, as a tuple.
+
+ .. attribute:: tuple
+
+ A tuple representing the envelope.
+
+ .. attribute:: wkt
+
+ A string representing this envelope as a polygon in WKT format.
+
+
+ .. method:: expand_to_include(self, *args)
+
+ .. versionadded:: 1.1
+
+Coordinate System Objects
+=========================
+
+``SpatialReference``
+--------------------
+
+.. class:: SpatialReference(srs_input)
+
+ Spatial reference objects are initialized on the given ``srs_input``,
+ which may be one of the following:
+
+ * OGC Well Known Text (WKT) (a string)
+ * EPSG code (integer or string)
+ * PROJ.4 string
+ * A shorthand string for well-known standards (``'WGS84'``, ``'WGS72'``, ``'NAD27'``, ``'NAD83'``)
+
+ Example::
+
+ >>> wgs84 = SpatialReference('WGS84') # shorthand string
+ >>> wgs84 = SpatialReference(4326) # EPSG code
+ >>> wgs84 = SpatialReference('EPSG:4326') # EPSG string
+ >>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
+ >>> wgs84 = SpatialReference(proj4) # PROJ.4 string
+ >>> wgs84 = SpatialReference("""GEOGCS["WGS 84",
+ DATUM["WGS_1984",
+ SPHEROID["WGS 84",6378137,298.257223563,
+ AUTHORITY["EPSG","7030"]],
+ AUTHORITY["EPSG","6326"]],
+ PRIMEM["Greenwich",0,
+ AUTHORITY["EPSG","8901"]],
+ UNIT["degree",0.01745329251994328,
+ AUTHORITY["EPSG","9122"]],
+ AUTHORITY["EPSG","4326"]]""") # OGC WKT
+
+ .. method:: __getitem__(target)
+
+ Returns the value of the given string attribute node, ``None`` if the node
+ doesn't exist. Can also take a tuple as a parameter, (target, child),
+ where child is the index of the attribute in the WKT. For example::
+
+ >>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]')
+ >>> srs = SpatialReference(wkt) # could also use 'WGS84', or 4326
+ >>> print srs['GEOGCS']
+ WGS 84
+ >>> print srs['DATUM']
+ WGS_1984
+ >>> print srs['AUTHORITY']
+ EPSG
+ >>> print srs['AUTHORITY', 1] # The authority value
+ 4326
+ >>> print srs['TOWGS84', 4] # the fourth value in this wkt
+ 0
+ >>> print srs['UNIT|AUTHORITY'] # For the units authority, have to use the pipe symbole.
+ EPSG
+ >>> print srs['UNIT|AUTHORITY', 1] # The authority value for the untis
+ 9122
+
+ .. method:: attr_value(target, index=0)
+
+ The attribute value for the given target node (e.g. ``'PROJCS'``).
+ The index keyword specifies an index of the child node to return.
+
+ .. method:: auth_name(target)
+
+ Returns the authority name for the given string target node.
+
+ .. method:: auth_code(target)
+
+ Returns the authority code for the given string target node.
+
+ .. method:: clone()
+
+ Returns a clone of this spatial reference object.
+
+ .. method:: identify_epsg()
+
+ This method inspects the WKT of this SpatialReference, and will
+ add EPSG authority nodes where an EPSG identifier is applicable.
+
+ .. method:: from_esri()
+
+ Morphs this SpatialReference from ESRI's format to EPSG
+
+ .. method:: to_esri()
+
+ Morphs this SpatialReference to ESRI's format.
+
+ .. method:: validate()
+
+ Checks to see if the given spatial reference is valid, if not
+ an exception will be raised.
+
+ .. method:: import_epsg(epsg)
+
+ Import spatial reference from EPSG code.
+
+ .. method:: import_proj(proj)
+
+ Import spatial reference from PROJ.4 string.
+
+ .. method:: import_user_input(user_input)
+
+ .. versionadded:: 1.1
+
+ .. method:: import_wkt(wkt)
+
+ Import spatial reference from WKT.
+
+ .. method:: import_xml(xml)
+
+ Import spatial reference from XML.
+
+ .. attribute:: name
+
+ Returns the name of this Spatial Reference.
+
+ .. attribute:: srid
+
+ Returns the SRID of top-level authority, or ``None`` if undefined.
+
+ .. attribute:: linear_name
+
+ Returns the name of the linear units.
+
+ .. attribute:: linear_units
+
+ Returns the value of the linear units.
+
+ .. attribute:: angular_name
+
+ Returns the name of the angular units."
+
+ .. attribute:: angular_units
+
+ Returns the value of the angular units.
+
+ .. attribute:: units
+
+ Returns a 2-tuple of the units value and the units name,
+ and will automatically determines whether to return the linear
+ or angular units.
+
+ .. attribute:: ellisoid
+
+ Returns a tuple of the ellipsoid parameters for this spatial
+ reference: (semimajor axis, semiminor axis, and inverse flattening)
+
+ .. attribute:: semi_major
+
+ Returns the semi major axis of the ellipsoid for this spatial reference.
+
+ .. attribute:: semi_minor
+
+ Returns the semi minor axis of the ellipsoid for this spatial reference.
+
+ .. attribute:: inverse_flattening
+
+ Returns the inverse flattening of the ellipsoid for this spatial reference.
+
+ .. attribute:: geographic
+
+ Returns ``True`` if this spatial reference is geographic
+ (root node is ``GEOGCS``).
+
+ .. attribute:: local
+
+ Returns ``True`` if this spatial reference is local
+ (root node is ``LOCAL_CS``).
+
+ .. attribute:: projected
+
+ Returns ``True`` if this spatial reference is a projected coordinate
+ system (root node is ``PROJCS``).
+
+ .. attribute:: wkt
+
+ Returns the WKT representation of this spatial reference.
+
+ .. attribute:: pretty_wkt
+
+ Returns the 'pretty' representation of the WKT.
+
+ .. attribute:: proj
+
+ Returns the PROJ.4 representation for this spatial reference.
+
+ .. attribute:: proj4
+
+ Alias for :attr:`SpatialReference.proj`.
+
+ .. attribute:: xml
+
+ Returns the XML representation of this spatial reference.
+
+
+``CoordTransform``
+------------------
+
+.. class:: CoordTransform(source, target)
+
+Represents a coordinate system transform. It is initialized with two
+:class:`SpatialReference`, representing the source and target coordinate
+systems, respectively. These objects should be used when performing
+the same coordinate transformation repeatedly on different geometries::
+
+ >>> ct = CoordTransform(SpatialReference('WGS84'), SpatialReference('NAD83'))
+ >>> for feat in layer:
+ ... geom = feat.geom # getting clone of feature geometry
+ ... geom.transform(ct) # transforming
+
+Settings
+========
+
+.. setting:: GDAL_LIBRARY_PATH
+
+GDAL_LIBRARY_PATH
+-----------------
+
+A string specifying the location of the GDAL library. Typically,
+this setting is only used if the GDAL library is in a non-standard
+location (e.g., ``/home/john/lib/libgdal.so``).
View
223 docs/ref/contrib/gis/geoip.txt
@@ -0,0 +1,223 @@
+.. _ref-geoip:
+
+======================
+Geolocation with GeoIP
+======================
+
+.. module:: django.contrib.gis.utils.geoip
+ :synopsis: High-level Python interface for MaxMind's GeoIP C library.
+
+.. currentmodule:: django.contrib.gis.utils
+
+The :class:`GeoIP` object is a ctypes wrapper for the
+`MaxMind GeoIP C API`__. [#]_ This interface is a BSD-licensed alternative
+to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.
+
+In order to perform IP-based geolocation, the :class:`GeoIP` object requires
+the GeoIP C libary and either the GeoIP `Country`__ or `City`__
+datasets in binary format (the CSV files will not work!). These datasets may be
+`downloaded from MaxMind`__. Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz``
+and unzip them in a directory corresponding to what you set
+``GEOIP_PATH`` with in your settings. See the example and reference below
+for more details.
+
+__ http://www.maxmind.com/app/c
+__ http://www.maxmind.com/app/python
+__ http://www.maxmind.com/app/country
+__ http://www.maxmind.com/app/city
+__ http://www.maxmind.com/download/geoip/database/
+
+Example
+=======
+
+Assuming you have the GeoIP C library installed, here is an example of its
+usage::
+
+ >>> from django.contrib.gis.utils import GeoIP
+ >>> g = GeoIP()
+ >>> g.country('google.com')
+ {'country_code': 'US', 'country_name': 'United States'}
+ >>> g.city('72.14.207.99')
+ {'area_code': 650,
+ 'city': 'Mountain View',
+ 'country_code': 'US',
+ 'country_code3': 'USA',
+ 'country_name': 'United States',
+ 'dma_code': 807,
+ 'latitude': 37.419200897216797,
+ 'longitude': -122.05740356445312,
+ 'postal_code': '94043',
+ 'region': 'CA'}
+ >>> g.lat_lon('salon.com')
+ (37.789798736572266, -122.39420318603516)
+ >>> g.lon_lat('uh.edu')
+ (-95.415199279785156, 29.77549934387207)
+ >>> g.geos('24.124.1.80').wkt
+ 'POINT (-95.2087020874023438 39.0392990112304688)'
+
+``GeoIP`` Settings
+==================
+
+.. setting:: GEOIP_PATH
+
+GEOIP_PATH
+----------
+
+A string specifying the directory where the GeoIP data files are
+located. This setting is *required* unless manually specified
+with ``path`` keyword when initializing the :class:`GeoIP` object.
+
+.. setting:: GEOIP_LIBRARY_PATH
+
+GEOIP_LIBRARY_PATH
+------------------
+
+A string specifying the location of the GeoIP C library. Typically,
+this setting is only used if the GeoIP C library is in a non-standard
+location (e.g., ``/home/sue/lib/libGeoIP.so``).
+
+.. setting:: GEOIP_COUNTRY
+
+GEOIP_COUNTRY
+-------------
+
+The basename to use for the GeoIP country data file.
+Defaults to ``'GeoIP.dat'``.
+
+.. setting:: GEOIP_CITY
+
+GEOIP_CITY
+----------
+
+The basename to use for the GeoIP city data file.
+Defaults to ``'GeoLiteCity.dat'``.
+
+``GeoIP`` API
+=============
+
+.. class:: GeoIP([path=None, cache=0, country=None, city=None])
+
+The ``GeoIP`` object does not require any parameters to use the default
+settings. However, at the very least the :setting:`GEOIP_PATH` setting
+should be set with the path of the location of your GeoIP data sets. The
+following intialization keywords may be used to customize any of the
+defaults.
+
+=================== =======================================================
+Keyword Arguments Description
+=================== =======================================================
+``path`` Base directory to where GeoIP data is located or the
+ full path to where the city or country data files
+ (.dat) are located. Assumes that both the city and
+ country data sets are located in this directory;
+ overrides the :setting:`GEOIP_PATH` settings attribute.
+
+``cache`` The cache settings when opening up the GeoIP datasets,
+ and may be an integer in (0, 1, 2, 4) corresponding to
+ the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``,
+ ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE``
+ ``GeoIPOptions`` C API settings, respectively.
+ Defaults to 0 (``GEOIP_STANDARD``).
+
+``country`` The name of the GeoIP country data file. Defaults
+ to ``GeoIP.dat``. Setting this keyword overrides the
+ :setting:`GEOIP_COUNTRY` settings attribute.
+
+``city`` The name of the GeoIP city data file. Defaults to
+ ``GeoLiteCity.dat``. Setting this keyword overrides
+ the :setting:`GEOIP_CITY` settings attribute.
+=================== =======================================================
+
+``GeoIP`` Methods
+=================
+
+Querying
+--------
+
+All the following querying routines may take either a string IP address
+or a fully qualified domain name (FQDN). For example, both
+``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query
+parameters.
+
+.. method:: GeoIP.city(query)
+
+Returns a dictionary of city information for the given query. Some
+of the values in the dictionary may be undefined (``None``).
+
+.. method:: GeoIPcountry(query)
+
+Returns a dictionary with the country code and country for the given
+query.
+
+.. method:: GeoIP.country_code(query)
+
+Returns only the country code corresponding to the query.
+
+.. method:: GeoIP.country_name(query)
+
+Returns only the country name corresponding to the query.
+
+Coordinate Retrieval
+--------------------
+
+.. method:: GeoIP.coords(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lon_lat(query)
+
+Returns a coordinate tuple of (longitude, latitude).
+
+.. method:: GeoIP.lat_lon(query)
+
+Returns a coordinate tuple of (latitude, longitude),
+
+.. method:: GeoIP.geos(query)
+
+Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.
+
+Database Information
+--------------------
+
+.. attribute:: GeoIP.country_info
+
+This property returns information about the GeoIP country database.
+
+.. attribute:: GeoIP.city_info
+
+This property returns information about the GeoIP city database.
+
+.. attribute:: GeoIP.info
+
+This property returns information about all GeoIP databases (both city
+and country).
+
+GeoIP-Python API compatibility methods
+----------------------------------------
+
+These methods exist to ease compatibility with any code using MaxMind's
+existing Python API.
+
+.. classmethod:: GeoIP.open(path, cache)
+
+This classmethod instantiates the GeoIP object from the given database path
+and given cache setting.
+
+.. method:: GeoIP.regioin_by_addr(query)
+
+.. method:: GeoIP.region_by_name(query)
+
+.. method:: GeoIP.record_by_addr(query)
+
+.. method:: GeoIP.record_by_name(query)
+
+.. method:: GeoIP.country_code_by_addr(query)
+
+.. method:: GeoIP.country_code_by_name(query)
+
+.. method:: GeoIP.country_name_by_addr(query)
+
+.. method:: GeoIP.country_name_by_name(query)
+
+.. rubric:: Footnotes
+.. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts.
View
1,256 docs/ref/contrib/gis/geoquerysets.txt
@@ -0,0 +1,1256 @@
+.. _ref-geoquerysets:
+
+=========================
+GeoQuerySet API Reference
+=========================
+
+.. currentmodule:: django.contrib.gis.db.models
+
+.. class:: GeoQuerySet([model=None])
+
+
+.. _spatial-lookups:
+
+Spatial Lookups
+===============
+
+Just like when using the the :ref:`queryset-api`, interaction
+with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`.
+Instead of the regular Django :ref:`field-lookups`, the
+spatial lookups in this section are available for :class:`GeometryField`.
+
+For an introduction, see the :ref:`spatial lookups introduction
+<spatial-lookups-intro>`. For an overview of what lookups are
+compatible with a particular spatial backend, refer to the
+:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`.
+
+.. fieldlookup:: bbcontains
+
+bbcontains
+----------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box completely contains the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__bbcontains=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``poly ~ geom``
+MySQL ``MBRContains(poly, geom)``
+SpatiaLite ``MbrContains(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: bboverlaps
+
+bboverlaps
+----------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box overlaps the lookup geometry's
+bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__bboverlaps=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``poly && geom``
+MySQL ``MBROverlaps(poly, geom)``
+SpatiaLite ``MbrOverlaps(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: contained
+
+contained
+---------
+
+*Availability*: PostGIS, MySQL, SpatiaLite
+
+Tests if the geometry field's bounding box is completely contained by the
+lookup geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__contained=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``poly @ geom``
+MySQL ``MBRWithin(poly, geom)``
+SpatiaLite ``MbrWithin(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: gis-contains
+
+contains
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially contains the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__contains=geom)
+
+========== ============================
+Backend SQL Equivalent
+========== ============================
+PostGIS ``ST_Contains(poly, geom)``
+Oracle ``SDO_CONTAINS(poly, geom)``
+MySQL ``MBRContains(poly, geom)``
+SpatiaLite ``Contains(poly, geom)``
+========== ============================
+
+.. fieldlookup:: contains_properly
+
+contains_properly
+-----------------
+
+.. versionadded:: 1.2
+
+*Availability*: PostGIS
+
+Returns true if the lookup geometry intersects the interior of the
+geometry field, but not the boundary (or exterior). [#fncontainsproperly]_
+
+.. note::
+
+ Requires PostGIS 1.4 and above.
+
+Example::
+
+ Zipcode.objects.filter(poly__contains_properly=geom)
+
+========== ===================================
+Backend SQL Equivalent
+========== ===================================
+PostGIS ``ST_ContainsProperly(poly, geom)``
+========== ===================================
+
+.. fieldlookup:: coveredby
+
+coveredby
+---------
+
+*Availability*: PostGIS, Oracle
+
+Tests if no point in the geometry field is outside the lookup geometry.
+[#fncovers]_
+
+Example::
+
+ Zipcode.objects.filter(poly__coveredby=geom)
+
+========== =============================
+Backend SQL Equivalent
+========== =============================
+PostGIS ``ST_CoveredBy(poly, geom)``
+Oracle ``SDO_COVEREDBY(poly, geom)``
+========== =============================
+
+.. fieldlookup:: covers
+
+covers
+------
+
+*Availability*: PostGIS, Oracle
+
+Tests if no point in the lookup geometry is outside the geometry field.
+[#fncovers]_
+
+Example::
+
+ Zipcode.objects.filter(poly__covers=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``ST_Covers(poly, geom)``
+Oracle ``SDO_COVERS(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: crosses
+
+crosses
+-------
+
+*Availability*: PostGIS, SpatiaLite
+
+Tests if the geometry field spatially crosses the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__crosses=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``ST_Crosses(poly, geom)``
+SpatiaLite ``Crosses(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: disjoint
+
+disjoint
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field is spatially disjoint from the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__disjoint=geom)
+
+========== =================================================
+Backend SQL Equivalent
+========== =================================================
+PostGIS ``ST_Disjoint(poly, geom)``
+Oracle ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)``
+MySQL ``MBRDisjoint(poly, geom)``
+SpatiaLite ``Disjoint(poly, geom)``
+========== =================================================
+
+equals
+------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: exact
+.. fieldlookup:: same_as
+
+exact, same_as
+--------------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: intersects
+
+intersects
+----------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially intersects the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__intersects=geom)
+
+========== =================================================
+Backend SQL Equivalent
+========== =================================================
+PostGIS ``ST_Intersects(poly, geom)``
+Oracle ``SDO_OVERLAPBDYINTERSECT(poly, geom)``
+MySQL ``MBRIntersects(poly, geom)``
+SpatiaLite ``Intersects(poly, geom)``
+========== =================================================
+
+.. fieldlookup:: overlaps
+
+overlaps
+--------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+.. fieldlookup:: relate
+
+relate
+------
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+Tests if the geometry field is spatially related to the the lookup geometry by
+the values given in the given pattern. This lookup requires a tuple parameter,
+``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend:
+
+PostGIS & SpatiaLite
+~~~~~~~~~~~~~~~~~~~~
+On these spatial backends the intersection pattern is a string comprising
+nine characters, which define intersections between the interior, boundary,
+and exterior of the geometry field and the lookup geometry.
+The intersection pattern matrix may only use the following characters:
+``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune"
+a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_
+
+Example::
+
+ # A tuple lookup parameter is used to specify the geometry and
+ # the intersection pattern (the pattern here is for 'contains').
+ Zipcode.objects.filter(poly__relate(geom, 'T*T***FF*'))
+
+PostGIS SQL equivalent::
+
+ SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
+
+SpatiaLite SQL equivalent::
+
+ SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')
+
+Oracle
+~~~~~~
+
+Here the relation pattern is compreised at least one of the nine relation
+strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
+``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and
+``ANYINTERACT``. Multiple strings may be combined with the logical Boolean
+operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation
+strings are case-insensitive.
+
+Example::
+
+ Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
+
+Oracle SQL equivalent::
+
+ SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
+
+.. fieldlookup:: touches
+
+touches
+-------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field spatially touches the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__touches=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``ST_Touches(poly, geom)``
+MySQL ``MBRTouches(poly, geom)``
+Oracle ``SDO_TOUCH(poly, geom)``
+SpatiaLite ``Touches(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: within
+
+within
+------
+
+*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
+
+Tests if the geometry field is spatially within the lookup geometry.
+
+Example::
+
+ Zipcode.objects.filter(poly__within=geom)
+
+========== ==========================
+Backend SQL Equivalent
+========== ==========================
+PostGIS ``ST_Within(poly, geom)``
+MySQL ``MBRWithin(poly, geom)``
+Oracle ``SDO_INSIDE(poly, geom)``
+SpatiaLite ``Within(poly, geom)``
+========== ==========================
+
+.. fieldlookup:: left
+
+left
+----
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly to the left of the
+lookup geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__left=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly << geom
+
+.. fieldlookup:: right
+
+right
+-----
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly to the right of the
+lookup geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__right=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly >> geom
+
+.. fieldlookup:: overlaps_left
+
+overlaps_left
+-------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is to the left of the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__overlaps_left=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly &< geom
+
+
+.. fieldlookup:: overlaps_right
+
+overlaps_right
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is to the right of the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__overlaps_right=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly &> geom
+
+.. fieldlookup:: overlaps_above
+
+overlaps_above
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is above the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__overlaps_above=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly |&> geom
+
+.. fieldlookup:: overlaps_below
+
+overlaps_below
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box overlaps or is below the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__overlaps_below=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly &<| geom
+
+.. fieldlookup:: strictly_above
+
+strictly_above
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly above the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__strictly_above=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly |>> geom
+
+.. fieldlookup:: strictly_below
+
+strictly_below
+--------------
+
+*Availability*: PostGIS
+
+Tests if the geometry field's bounding box is strictly above the lookup
+geometry's bounding box.
+
+Example::
+
+ Zipcode.objects.filter(poly__strictly_above=geom)
+
+PostGIS equivalent::
+
+ SELECT ... WHERE poly |>> geom
+
+
+.. _distance-lookups:
+
+Distance Lookups
+================
+
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+For an overview on performing distance queries, please refer to
+the :ref:`distance queries introduction <distance-queries>`.
+
+Distance lookups take the following form::
+
+ <field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid'])
+
+The value passed into a distance lookup is a tuple; the first two
+values are mandatory, and are the geometry to calculate distances to,
+and a distance value (either a number in units of the field or a
+:class:`~django.contrib.gis.measure.Distance` object). On every
+distance lookup but :lookup:`dwithin`, an optional
+third element, ``'spheroid'``, may be included to tell GeoDjango
+to use the more accurate spheroid distance calculation functions on
+fields with a geodetic coordinate system (e.g., ``ST_Distance_Spheroid``
+would be used instead of ``ST_Distance_Sphere``).
+
+.. fieldlookup:: distance_gt
+
+distance_gt
+-----------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is greater than the given distance value.
+
+Example::
+
+ Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
+
+========== ===============================================
+Backend SQL Equivalent
+========== ===============================================
+PostGIS ``ST_Distance(poly, geom) > 5``
+Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5``
+SpatiaLite ``Distance(poly, geom) > 5``
+========== ===============================================
+
+.. fieldlookup:: distance_gte
+
+distance_gte
+------------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is greater than or equal to the given distance value.
+
+Example::
+
+ Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
+
+========== ================================================
+Backend SQL Equivalent
+========== ================================================
+PostGIS ``ST_Distance(poly, geom) >= 5``
+Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5``
+SpatiaLite ``Distance(poly, geom) >= 5``
+========== ================================================
+
+.. fieldlookup:: distance_lt
+
+distance_lt
+-----------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is less than the given distance value.
+
+Example::
+
+ Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
+
+========== ===============================================
+Backend SQL Equivalent
+========== ===============================================
+PostGIS ``ST_Distance(poly, geom) < 5``
+Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5``
+SpatiaLite ``Distance(poly, geom) < 5``
+========== ===============================================
+
+.. fieldlookup:: distance_lte
+
+distance_lte
+------------
+
+Returns models where the distance to the geometry field from the lookup
+geometry is less than or equal to the given distance value.
+
+Example::
+
+ Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
+
+========== ================================================
+Backend SQL Equivalent
+========== ================================================
+PostGIS ``ST_Distance(poly, geom) <= 5``
+Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5``
+SpatiaLite ``Distance(poly, geom) <= 5``
+========== ================================================
+
+.. fieldlookup:: dwithin
+
+dwithin
+-------
+
+Returns models where the distance to the geometry field from the
+lookup geometry are within the given distance from one another.
+
+Example::
+
+ Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
+
+========== ======================================
+Backend SQL Equivalent
+========== ======================================
+PostGIS ``ST_DWithin(poly, geom, 5)``
+Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
+========== ======================================
+
+.. note::
+
+ This lookup is not available on SpatiaLite.
+
+.. fieldlookup:: equals
+
+
+``GeoQuerySet`` Methods
+=======================
+
+``GeoQuerySet`` methods specify that a spatial operation be performed
+on each patial operation on each geographic
+field in the queryset and store its output in a new attribute on the model
+(which is generally the name of the ``GeoQuerySet`` method).
+
+There are also aggregate ``GeoQuerySet`` methods which return a single value
+instead of a queryset. This section will describe the API and availability
+of every ``GeoQuerySet`` method available in GeoDjango.
+
+.. note::
+
+ What methods are available depend on your spatial backend. See
+ the :ref:`compatibility table <geoqueryset-method-compatibility>`
+ for more details.
+
+With a few exceptions, the following keyword arguments may be used with all
+``GeoQuerySet`` methods:
+
+===================== =====================================================
+Keyword Argument Description
+===================== =====================================================
+``field_name`` By default, ``GeoQuerySet`` methods use the first
+ geographic field encountered in the model. This
+ keyword should be used to specify another
+ geographic field (e.g., ``field_name='point2'``)
+ when there are multiple geographic fields in a model.
+
+ On PostGIS, the ``field_name`` keyword may also be
+ used on geometry fields in models that are related
+ via a ``ForeignKey`` relation (e.g.,
+ ``field_name='related__point'``).
+
+``model_att`` By default, ``GeoQuerySet`` methods typically attach
+ their output in an attribute with the same name as
+ the ``GeoQuerySet`` method. Setting this keyword
+ with the desired attribute name will override this
+ default behavior. For example,
+ ``qs = Zipcode.objects.centroid(model_att='c')`` will
+ attach the centroid of the ``Zipcode`` geometry field
+ in a ``c`` attribute on every model rather than in a
+ ``centroid`` attribute.
+
+ This keyword is required if
+ a method name clashes with an existing
+ ``GeoQuerySet`` method -- if you wanted to use the
+ ``area()`` method on model with a ``PolygonField``
+ named ``area``, for example.
+===================== =====================================================
+
+Measurement
+-----------
+*Availability*: PostGIS, Oracle, SpatiaLite
+
+``area``
+~~~~~~~~
+
+.. method:: GeoQuerySet.area(**kwargs)
+
+Returns the area of the geographic field in an ``area`` attribute on
+each element of this GeoQuerySet.
+
+``distance``
+~~~~~~~~~~~~
+
+.. method:: GeoQuerySet.distance(geom, **kwargs)
+
+This method takes a geometry as a parameter, and attaches a ``distance``
+attribute to every model in the returned queryset that contains the
+distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry.
+
+In the following example (taken from the `GeoDjango distance tests`__),
+the distance from the `Tasmanian`__ city of Hobart to every other
+:class:`PointField` in the ``AustraliaCity`` queryset is calculated::
+
+ &g