1 | ===================
|
---|
2 | GeoDjango Model API
|
---|
3 | ===================
|
---|
4 |
|
---|
5 | .. currentmodule:: django.contrib.gis.db.models
|
---|
6 |
|
---|
7 | This document explores the details of the GeoDjango Model API. Throughout this
|
---|
8 | section, we'll be using the following geographic model of a `ZIP code`__ as our
|
---|
9 | example::
|
---|
10 |
|
---|
11 | from django.contrib.gis.db import models
|
---|
12 |
|
---|
13 | class Zipcode(models.Model):
|
---|
14 | code = models.CharField(max_length=5)
|
---|
15 | poly = models.PolygonField()
|
---|
16 | objects = models.GeoManager()
|
---|
17 |
|
---|
18 | __ http://en.wikipedia.org/wiki/ZIP_code
|
---|
19 |
|
---|
20 | Geometry Field Types
|
---|
21 | ====================
|
---|
22 |
|
---|
23 | The following geometry fields are available:
|
---|
24 |
|
---|
25 | * ``PointField``
|
---|
26 | * ``LineStringField``
|
---|
27 | * ``PolygonField``
|
---|
28 | * ``MultiPointField``
|
---|
29 | * ``MultiLineStringField``
|
---|
30 | * ``MultiPolygonField``
|
---|
31 | * ``GeometryCollectionField``
|
---|
32 |
|
---|
33 | Each of these fields correspond with OpenGIS Simple Features [#]_.
|
---|
34 |
|
---|
35 | Geometry Field Options
|
---|
36 | ----------------------
|
---|
37 |
|
---|
38 | In addition to the regular `field options`__ available for Django model fields,
|
---|
39 | geometry fields have the following additional options:
|
---|
40 |
|
---|
41 | ====================== ===================================================
|
---|
42 | Argument Description
|
---|
43 | ====================== ===================================================
|
---|
44 | ``srid`` Sets the SRID [#]_ (Spatial Reference System
|
---|
45 | Identity) of the geometry field to the given value.
|
---|
46 | Defaults to 4326 (also known as `WGS84`__, units
|
---|
47 | are in degrees of longitude and latitude).
|
---|
48 |
|
---|
49 | ``dim`` *New in version 1.2*
|
---|
50 |
|
---|
51 | Sets the coordinate dimension for the geometry
|
---|
52 | field. By default, it is 2 (for two-dimensional
|
---|
53 | geometries), but may be set to 3 if GeoDjango
|
---|
54 | supports 3D geometries for your spatial backend and
|
---|
55 | GEOS 3.1 is installed.
|
---|
56 |
|
---|
57 | ``spatial_index`` Defaults to True. Creates a spatial index for the
|
---|
58 | given geometry. Please note that this is different
|
---|
59 | from the ``db_index`` field option because
|
---|
60 | spatial indexes are created in a different manner
|
---|
61 | than regular database indexes.
|
---|
62 | ====================== ===================================================
|
---|
63 |
|
---|
64 | __ http://docs.djangoproject.com/en/dev/ref/models/fields/#field-options
|
---|
65 | __ http://en.wikipedia.org/wiki/WGS84
|
---|
66 |
|
---|
67 | Selecting an SRID
|
---|
68 | ^^^^^^^^^^^^^^^^^
|
---|
69 |
|
---|
70 | Choosing an appropriate SRID for your model is an important decision that the
|
---|
71 | developer should consider carefully. The SRID is an integer specifier that
|
---|
72 | corresponds to the projection system that will be used to interpret the data
|
---|
73 | in the spatial database. [#]_ Projection systems give the context to the
|
---|
74 | coordinates that specify a location. Although the details of `geodesy`__ are
|
---|
75 | beyond the scope of this documentation, the general problem is that the earth
|
---|
76 | is spherical and representations of the earth (e.g., paper maps, web maps)
|
---|
77 | are not.
|
---|
78 |
|
---|
79 | Most people are familiar with using latitude and longitude to reference a
|
---|
80 | location on the earth's surface. However, latitude and longitude are angles,
|
---|
81 | not distances. [#]_ In other words, while the shortest path between two points on
|
---|
82 | a flat surface is a straight line, the shortest path between two points on a curved
|
---|
83 | surface (such as the earth) is an *arc* of a `great circle`__. [#]_ Thus,
|
---|
84 | additional computation is required to obtain distances in planar units (e.g.,
|
---|
85 | kilometers and miles). Using a geographic coordinate system may introduce
|
---|
86 | complications for the developer later on. For example, PostGIS does not
|
---|
87 | have the capability to perform distance calculations between non-point
|
---|
88 | geometries using geographic coordinate systems, e.g., constructing a query to
|
---|
89 | find all points within 5 miles of a county boundary stored as WGS84. [#]_
|
---|
90 |
|
---|
91 | Portions of the earth's surface may projected onto a two-dimensional, or
|
---|
92 | Cartesian, plane. Projected coordinate systems are especially convenient
|
---|
93 | for region-specific applications, e.g., if you know that your database will
|
---|
94 | only cover geometries in `North Kansas`__, then you may consider using projection
|
---|
95 | system specific to that region. Moreover, projected coordinate systems are
|
---|
96 | defined in Cartesian units (such as meters or feet), easing distance
|
---|
97 | calculations.
|
---|
98 |
|
---|
99 | Additional Resources:
|
---|
100 |
|
---|
101 | * `spatialreference.org`__: A Django-powered database of spatial reference
|
---|
102 | systems.
|
---|
103 | * `The State Plane Coordinate System`__: A website covering the various
|
---|
104 | projection systems used in the United States. Much of the U.S. spatial
|
---|
105 | data encountered will be in one of these coordinate systems rather than
|
---|
106 | in a geographic coordinate system such as WGS84.
|
---|
107 |
|
---|
108 | __ http://en.wikipedia.org/wiki/Geodesy
|
---|
109 | __ http://en.wikipedia.org/wiki/Great_circle
|
---|
110 | __ http://www.spatialreference.org/ref/epsg/2796/
|
---|
111 | __ http://spatialreference.org/
|
---|
112 | __ http://welcome.warnercnr.colostate.edu/class_info/nr502/lg3/datums_coordinates/spcs.html
|
---|
113 |
|
---|
114 | ``GeoManager``
|
---|
115 | ==============
|
---|
116 |
|
---|
117 | In order to conduct geographic queries, each geographic model requires
|
---|
118 | a ``GeoManager`` model manager. This manager allows for the proper SQL
|
---|
119 | construction for geographic queries; thus, without it, all geographic filters
|
---|
120 | will fail. It should also be noted that ``GeoManager`` is required even if the
|
---|
121 | model does not have a geographic field itself, e.g., in the case of a
|
---|
122 | ``ForeignKey`` relation to a model with a geographic field. For example,
|
---|
123 | if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
|
---|
124 | model::
|
---|
125 |
|
---|
126 | from django.contrib.gis.db import models
|
---|
127 | from django.contrib.localflavor.us.models import USStateField
|
---|
128 |
|
---|
129 | class Address(models.Model):
|
---|
130 | num = models.IntegerField()
|
---|
131 | street = models.CharField(max_length=100)
|
---|
132 | city = models.CharField(max_length=100)
|
---|
133 | state = USStateField()
|
---|
134 | zipcode = models.ForeignKey(Zipcode)
|
---|
135 | objects = models.GeoManager()
|
---|
136 |
|
---|
137 | The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
|
---|
138 | for example::
|
---|
139 |
|
---|
140 | qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
|
---|
141 |
|
---|
142 | .. rubric:: Footnotes
|
---|
143 | .. [#] OpenGIS Consortium, Inc., `Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999).
|
---|
144 | .. [#] *See id.* at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems).
|
---|
145 | .. [#] 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.
|
---|
146 | .. [#] 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.
|
---|
147 | .. [#] 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.
|
---|
148 | .. [#] 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.
|
---|