===================
GeoDjango Model API
===================

.. currentmodule:: django.contrib.gis.db.models

This document explores the details of the GeoDjango Model API.  Throughout this
section, we'll be using the following geographic model of a `ZIP code`__ as our 
example::

    from django.contrib.gis.db import models
    
    class Zipcode(models.Model):
        code = models.CharField(max_length=5)
        poly = models.PolygonField()
        objects = models.GeoManager()

__ http://en.wikipedia.org/wiki/ZIP_code

Geometry Field Types
====================

The following geometry fields are available:

    * ``PointField``
    * ``LineStringField``
    * ``PolygonField``
    * ``MultiPointField``
    * ``MultiLineStringField``
    * ``MultiPolygonField``
    * ``GeometryCollectionField``

Each of these fields correspond with OpenGIS Simple Features [#]_.

Geometry Field Options
----------------------

In addition to the regular `field options`__ available for Django model fields, 
geometry fields have the following additional options:

======================  ===================================================
Argument                Description
======================  ===================================================
``srid``                Sets the SRID [#]_ (Spatial Reference System 
                        Identity) of the geometry field to the given value.
                        Defaults to 4326 (also known as `WGS84`__, units 
                        are in degrees of longitude and latitude).

``dim``			*New in version 1.2*

                        Sets the coordinate dimension for the geometry
                        field.  By default, it is 2 (for two-dimensional
			geometries), but may be set to 3 if GeoDjango
                        supports 3D geometries for your spatial backend and
			GEOS 3.1 is installed.

``spatial_index``       Defaults to True.  Creates a spatial index for the 
                        given geometry. Please note that this is different
                        from the ``db_index`` field option because 
                        spatial indexes are created in a different manner 
                        than regular database indexes. 
======================  ===================================================

__ http://docs.djangoproject.com/en/dev/ref/models/fields/#field-options
__ http://en.wikipedia.org/wiki/WGS84

Selecting an SRID
^^^^^^^^^^^^^^^^^

Choosing an appropriate SRID for your model is an important decision that the
developer should consider carefully.  The SRID is an integer specifier that 
corresponds to the projection system that will be used to interpret the data
in the spatial database. [#]_  Projection systems give the context to the
coordinates that specify a location.  Although the details of `geodesy`__ are
beyond the scope of this documentation, the general problem is that the earth
is spherical and representations of the earth (e.g., paper maps, web maps)
are not.

Most people are familiar with using latitude and longitude to reference a
location on the earth's surface.  However, latitude and longitude are angles,
not distances. [#]_  In other words, while the shortest path between two points on
a flat surface is a straight line, the shortest path between two points on a curved
surface (such as the earth) is an *arc* of a `great circle`__. [#]_  Thus,
additional computation is required to obtain distances in planar units (e.g., 
kilometers and miles).  Using a geographic coordinate system may introduce
complications for the developer later on.  For example, PostGIS does not
have the capability to perform distance calculations between non-point
geometries using geographic coordinate systems, e.g., constructing a query to 
find all points within 5 miles of a county boundary stored as WGS84. [#]_

Portions of the earth's surface may projected onto a two-dimensional, or 
Cartesian, plane.  Projected coordinate systems are especially convenient
for region-specific applications, e.g., if you know that your database will
only cover geometries in `North Kansas`__, then you may consider using projection 
system specific to that region.  Moreover, projected coordinate systems are 
defined in Cartesian units (such as meters or feet), easing distance 
calculations.

Additional Resources:

* `spatialreference.org`__: A Django-powered database of spatial reference 
  systems.
* `The State Plane Coordinate System`__: A website covering the various
  projection systems used in the United States.  Much of the U.S. spatial
  data encountered will be in one of these coordinate systems rather than
  in a geographic coordinate system such as WGS84.

__ http://en.wikipedia.org/wiki/Geodesy
__ http://en.wikipedia.org/wiki/Great_circle
__ http://www.spatialreference.org/ref/epsg/2796/
__ http://spatialreference.org/
__ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html

``GeoManager``
==============

In order to conduct geographic queries, each geographic model requires 
a ``GeoManager`` model manager.  This manager allows for the proper SQL
construction for geographic queries; thus, without it, all geographic filters 
will fail.  It should also be noted that ``GeoManager`` is required even if the
model does not have a geographic field itself, e.g., in the case of a 
``ForeignKey`` relation to a model with a geographic field.  For example, 
if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode`` 
model::

    from django.contrib.gis.db import models
    from django.contrib.localflavor.us.models import USStateField

    class Address(models.Model):
        num = models.IntegerField()
        street = models.CharField(max_length=100)
        city = models.CharField(max_length=100)
        state = USStateField()
        zipcode = models.ForeignKey(Zipcode)
        objects = models.GeoManager()

The geographic manager is needed to do spatial queries on related ``Zipcode`` objects, 
for example::

    qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')

.. rubric:: Footnotes
.. [#] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
.. [#] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
.. [#] Typically, SRID integer corresponds to an EPSG (`European Petroleum Survey Group <http://www.epsg.org>`_) identifier.  However, it may also be associated with custom projections defined in spatial database's spatial reference systems table.
.. [#] Harvard Graduate School of Design, `An Overview of Geodesy and Geographic Referencing Systems <http://www.gsd.harvard.edu/gis/manual/projections/fundamentals/>`_.  This is an excellent resource for an overview of principles relating to geographic and Cartesian coordinate systems. 
.. [#] Terry A. Slocum, Robert B. McMaster, Fritz C. Kessler, & Hugh H. Howard, *Thematic Cartography and Geographic Visualization* (Prentice Hall, 2nd edition), at Ch. 7.1.3.
.. [#] This isn't impossible using GeoDjango; you could for example, take a known point in a projected coordinate system, buffer it to the appropriate radius, and then perform an intersection operation with the buffer transformed to the geographic coordinate system.
