Ticket #12930: model-api.txt

File model-api.txt, 7.2 KB (added by adamfast, 16 years ago)

model-api.txt file to replace the one in place after applying the patch

Line 
1===================
2GeoDjango Model API
3===================
4
5.. currentmodule:: django.contrib.gis.db.models
6
7This document explores the details of the GeoDjango Model API. Throughout this
8section, we'll be using the following geographic model of a `ZIP code`__ as our
9example::
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
20Geometry Field Types
21====================
22
23The following geometry fields are available:
24
25 * ``PointField``
26 * ``LineStringField``
27 * ``PolygonField``
28 * ``MultiPointField``
29 * ``MultiLineStringField``
30 * ``MultiPolygonField``
31 * ``GeometryCollectionField``
32
33Each of these fields correspond with OpenGIS Simple Features [#]_.
34
35Geometry Field Options
36----------------------
37
38In addition to the regular `field options`__ available for Django model fields,
39geometry fields have the following additional options:
40
41====================== ===================================================
42Argument 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
67Selecting an SRID
68^^^^^^^^^^^^^^^^^
69
70Choosing an appropriate SRID for your model is an important decision that the
71developer should consider carefully. The SRID is an integer specifier that
72corresponds to the projection system that will be used to interpret the data
73in the spatial database. [#]_ Projection systems give the context to the
74coordinates that specify a location. Although the details of `geodesy`__ are
75beyond the scope of this documentation, the general problem is that the earth
76is spherical and representations of the earth (e.g., paper maps, web maps)
77are not.
78
79Most people are familiar with using latitude and longitude to reference a
80location on the earth's surface. However, latitude and longitude are angles,
81not distances. [#]_ In other words, while the shortest path between two points on
82a flat surface is a straight line, the shortest path between two points on a curved
83surface (such as the earth) is an *arc* of a `great circle`__. [#]_ Thus,
84additional computation is required to obtain distances in planar units (e.g.,
85kilometers and miles). Using a geographic coordinate system may introduce
86complications for the developer later on. For example, PostGIS does not
87have the capability to perform distance calculations between non-point
88geometries using geographic coordinate systems, e.g., constructing a query to
89find all points within 5 miles of a county boundary stored as WGS84. [#]_
90
91Portions of the earth's surface may projected onto a two-dimensional, or
92Cartesian, plane. Projected coordinate systems are especially convenient
93for region-specific applications, e.g., if you know that your database will
94only cover geometries in `North Kansas`__, then you may consider using projection
95system specific to that region. Moreover, projected coordinate systems are
96defined in Cartesian units (such as meters or feet), easing distance
97calculations.
98
99Additional 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
117In order to conduct geographic queries, each geographic model requires
118a ``GeoManager`` model manager. This manager allows for the proper SQL
119construction for geographic queries; thus, without it, all geographic filters
120will fail. It should also be noted that ``GeoManager`` is required even if the
121model 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,
123if we had an ``Address`` model with a ``ForeignKey`` to our ``Zipcode``
124model::
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
137The geographic manager is needed to do spatial queries on related ``Zipcode`` objects,
138for 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.
Back to Top