PageRenderTime 236ms CodeModel.GetById 232ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/ref/contrib/gis/model-api.txt

https://code.google.com/p/mango-py/
Plain Text | 265 lines | 193 code | 72 blank | 0 comment | 0 complexity | 81393970f45dc3a568290be0ddd051bd MD5 | raw file
  1.. _ref-gis-model-api:
  2
  3===================
  4GeoDjango Model API
  5===================
  6
  7.. module:: django.contrib.gis.db.models
  8   :synopsis: GeoDjango model and field API.
  9
 10This document explores the details of the GeoDjango Model API.  Throughout this
 11section, we'll be using the following geographic model of a `ZIP code`__ as our
 12example::
 13
 14    from django.contrib.gis.db import models
 15
 16    class Zipcode(models.Model):
 17        code = models.CharField(max_length=5)
 18        poly = models.PolygonField()
 19        objects = models.GeoManager()
 20
 21__ http://en.wikipedia.org/wiki/ZIP_code
 22
 23Geometry Field Types
 24====================
 25
 26Each of the following geometry field types correspond with the
 27OpenGIS Simple Features specification [#fnogc]_.
 28
 29``GeometryField``
 30-----------------
 31
 32.. class:: GeometryField
 33
 34``PointField``
 35--------------
 36
 37.. class:: PointField
 38
 39``LineStringField``
 40-------------------
 41
 42.. class:: LineStringField
 43
 44``PolygonField``
 45----------------
 46
 47.. class:: PolygonField
 48
 49``MultiPointField``
 50-------------------
 51
 52.. class:: MultiPointField
 53
 54``MultiLineStringField``
 55------------------------
 56
 57.. class:: MultiLineStringField
 58
 59``MultiPolygonField``
 60---------------------
 61
 62.. class:: MultiPolygonField
 63
 64``GeometryCollectionField``
 65---------------------------
 66
 67.. class:: GeometryCollectionField
 68
 69.. _geometry-field-options:
 70
 71Geometry Field Options
 72======================
 73
 74In addition to the regular :ref:`common-model-field-options` available for
 75Django model fields, geometry fields have the following additional options.
 76All are optional.
 77
 78``srid``
 79--------
 80
 81.. attribute:: GeometryField.srid
 82
 83Sets the SRID [#fnogcsrid]_ (Spatial Reference System Identity) of the geometry field to
 84the given value. Defaults to 4326 (also known as `WGS84`__, units are in degrees
 85of longitude and latitude).
 86
 87__ http://en.wikipedia.org/wiki/WGS84
 88
 89.. _selecting-an-srid:
 90
 91Selecting an SRID
 92^^^^^^^^^^^^^^^^^
 93
 94Choosing an appropriate SRID for your model is an important decision that the
 95developer should consider carefully.  The SRID is an integer specifier that
 96corresponds to the projection system that will be used to interpret the data
 97in the spatial database. [#fnsrid]_  Projection systems give the context to the
 98coordinates that specify a location.  Although the details of `geodesy`__ are
 99beyond the scope of this documentation, the general problem is that the earth
100is spherical and representations of the earth (e.g., paper maps, Web maps)
101are not.
102
103Most people are familiar with using latitude and longitude to reference a
104location on the earth's surface.  However, latitude and longitude are angles,
105not distances. [#fnharvard]_  In other words, while the shortest path between two points on
106a flat surface is a straight line, the shortest path between two points on a curved
107surface (such as the earth) is an *arc* of a `great circle`__. [#fnthematic]_  Thus,
108additional computation is required to obtain distances in planar units (e.g.,
109kilometers and miles).  Using a geographic coordinate system may introduce
110complications for the developer later on.  For example, PostGIS versions 1.4
111and below do not have the capability to perform distance calculations between
112non-point geometries using geographic coordinate systems, e.g., constructing a
113query to  find all points within 5 miles of a county boundary stored as WGS84.
114[#fndist]_
115
116Portions of the earth's surface may projected onto a two-dimensional, or
117Cartesian, plane.  Projected coordinate systems are especially convenient
118for region-specific applications, e.g., if you know that your database will
119only cover geometries in `North Kansas`__, then you may consider using projection
120system specific to that region.  Moreover, projected coordinate systems are
121defined in Cartesian units (such as meters or feet), easing distance
122calculations.
123
124.. note::
125
126    If you wish to peform arbitrary distance queries using non-point
127    geometries in WGS84, consider upgrading to PostGIS 1.5. For
128    better performance, enable the :attr:`GeometryField.geography`
129    keyword so that :ref:`geography database type <geography-type>`
130    is used instead.
131
132Additional Resources:
133
134* `spatialreference.org`__: A Django-powered database of spatial reference
135  systems.
136* `The State Plane Coordinate System`__: A Web site covering the various
137  projection systems used in the United States.  Much of the U.S. spatial
138  data encountered will be in one of these coordinate systems rather than
139  in a geographic coordinate system such as WGS84.
140
141__ http://en.wikipedia.org/wiki/Geodesy
142__ http://en.wikipedia.org/wiki/Great_circle
143__ http://www.spatialreference.org/ref/epsg/2796/
144__ http://spatialreference.org/
145__ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
146
147``spatial_index``
148-----------------
149
150.. attribute:: GeometryField.spatial_index
151
152Defaults to ``True``.  Creates a spatial index for the given geometry
153field.
154
155.. note::
156
157    This is different from the ``db_index`` field option because spatial
158    indexes are created in a different manner than regular database
159    indexes.  Specifically, spatial indexes are typically created using
160    a variant of the R-Tree, while regular database indexes typically
161    use B-Trees.
162
163``dim``
164-------
165
166.. versionadded:: 1.2
167
168.. attribute:: GeometryField.dim
169
170This option may be used for customizing the coordinate dimension of the
171geometry field.  By default, it is set to 2, for representing two-dimensional
172geometries.  For spatial backends that support it, it may be set to 3 for
173three-dimensonal support.
174
175.. note::
176
177    At this time 3D support requires that GEOS 3.1 be installed, and is
178    limited only to the PostGIS spatial backend.
179
180``geography``
181-------------
182
183.. versionadded:: 1.2
184
185.. attribute:: GeometryField.geography
186
187If set to ``True``, this option will create a database column of
188type geography, rather than geometry.  Please refer to the
189:ref:`geography type <geography-type>` section below for more
190details.
191
192.. note::
193
194    Geography support is limited only to PostGIS 1.5+, and will
195    force the SRID to be 4326.
196
197.. _geography-type:
198
199Geography Type
200^^^^^^^^^^^^^^
201
202In PostGIS 1.5, the geography type was introduced -- it provides
203provides native support for spatial features represented with geographic
204coordinates (e.g., WGS84 longitude/latitude). [#fngeography]_
205Unlike the plane used by a geometry type, the geography type uses a spherical
206representation of its data.  Distance and measurement operations
207performed on a geography column automatically employ great circle arc
208calculations and return linear units.  In other words, when ``ST_Distance``
209is called on two geographies, a value in meters is returned (as opposed
210to degrees if called on a geometry column in WGS84).
211
212Because geography calculations involve more mathematics, only a subset of the
213PostGIS spatial lookups are available for the geography type. Practically,
214this means that in addition to the :ref:`distance lookups <distance-lookups>`
215only the following additional :ref:`spatial lookups <spatial-lookups>` are
216available for geography columns:
217
218* :lookup:`bboverlaps`
219* :lookup:`coveredby`
220* :lookup:`covers`
221* :lookup:`intersects`
222
223For more information, the PostGIS documentation contains a helpful section on
224determining `when to use geography data type over geometry data type
225<http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_GeographyVSGeometry>`_.
226
227``GeoManager``
228==============
229
230.. currentmodule:: django.contrib.gis.db.models
231.. class:: GeoManager
232
233In order to conduct geographic queries, each geographic model requires
234a ``GeoManager`` model manager.  This manager allows for the proper SQL
235construction for geographic queries; thus, without it, all geographic filters
236will fail.  It should also be noted that ``GeoManager`` is required even if the
237model does not have a geographic field itself, e.g., in the case of a
238``ForeignKey`` relation to a model with a geographic field.  For example,
239if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
240model::
241
242    from django.contrib.gis.db import models
243    from django.contrib.localflavor.us.models import USStateField
244
245    class Address(models.Model):
246        num = models.IntegerField()
247        street = models.CharField(max_length=100)
248        city = models.CharField(max_length=100)
249        state = USStateField()
250        zipcode = models.ForeignKey(Zipcode)
251        objects = models.GeoManager()
252
253The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
254for example::
255
256    qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
257
258.. rubric:: Footnotes
259.. [#fnogc] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
260.. [#fnogcsrid] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
261.. [#fnsrid] 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.
262.. [#fnharvard] 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.
263.. [#fnthematic] 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.
264.. [#fndist] This limitation does not apply to PostGIS 1.5.  It should be noted that even in previous versions of PostGIS, 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.
265.. [#fngeography] Please refer to the `PostGIS Geography Type <http://postgis.refractions.net/documentation/manual-1.5/ch04.html#PostGIS_Geography>`_ documentation for more details.