Debian Codegraph @

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

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