| 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. |