GeoDjango Model API¶
This document explores the details of the GeoDjango Model API. Throughout this section, we’ll be using the following geographic model of a ZIP code and of a Digital Elevation Model as our examples:
from django.contrib.gis.db import models
class Zipcode(models.Model):
code = models.CharField(max_length=5)
poly = models.PolygonField()
class Elevation(models.Model):
name = models.CharField(max_length=100)
rast = models.RasterField()
Spatial Field Types¶
Spatial fields consist of a series of geometry field types and one raster field type. Each of the geometry field types correspond to the OpenGIS Simple Features specification [1]. There is no such standard for raster data.
Spatial Field Options¶
The geometry field options srid and spatial_index are now shared by
GeometryField and RasterField through the BaseSpatialField.
In addition to the regular Field options available for Django model fields, spatial fields have the following additional options. All are optional.
srid¶
-
BaseSpatialField.srid¶
Sets the SRID [2] (Spatial Reference System Identity) of the geometry field to the given value. Defaults to 4326 (also known as WGS84, units are in degrees of longitude and latitude).
Selecting an SRID¶
Choosing an appropriate SRID for your model is an important decision that the developer should consider carefully. The SRID is an integer specifier that corresponds to the projection system that will be used to interpret the data in the spatial database. [3] Projection systems give the context to the coordinates that specify a location. Although the details of geodesy are beyond the scope of this documentation, the general problem is that the earth is spherical and representations of the earth (e.g., paper maps, Web maps) are not.
Most people are familiar with using latitude and longitude to reference a location on the earth’s surface. However, latitude and longitude are angles, not distances. In other words, while the shortest path between two points on a flat surface is a straight line, the shortest path between two points on a curved surface (such as the earth) is an arc of a great circle. [4] Thus, additional computation is required to obtain distances in planar units (e.g., kilometers and miles). Using a geographic coordinate system may introduce complications for the developer later on. For example, SpatiaLite does not have the capability to perform distance calculations between geometries using geographic coordinate systems, e.g. constructing a query to find all points within 5 miles of a county boundary stored as WGS84. [5]
Portions of the earth’s surface may projected onto a two-dimensional, or Cartesian, plane. Projected coordinate systems are especially convenient for region-specific applications, e.g., if you know that your database will only cover geometries in North Kansas, then you may consider using projection system specific to that region. Moreover, projected coordinate systems are defined in Cartesian units (such as meters or feet), easing distance calculations.
Note
If you wish to perform arbitrary distance queries using non-point
geometries in WGS84 in PostGIS and you want decent performance, enable the
GeometryField.geography keyword so that geography database
type is used instead.
Additional Resources:
- spatialreference.org: A Django-powered database of spatial reference systems.
- The State Plane Coordinate System: A website covering the various projection systems used in the United States. Much of the U.S. spatial data encountered will be in one of these coordinate systems rather than in a geographic coordinate system such as WGS84.
spatial_index¶
-
BaseSpatialField.spatial_index¶
Defaults to True. Creates a spatial index for the given geometry
field.
Note
This is different from the db_index field option because spatial
indexes are created in a different manner than regular database
indexes. Specifically, spatial indexes are typically created using
a variant of the R-Tree, while regular database indexes typically
use B-Trees.
Geometry Field Options¶
There are additional options available for Geometry fields. All the following options are optional.
dim¶
-
GeometryField.dim¶
This option may be used for customizing the coordinate dimension of the geometry field. By default, it is set to 2, for representing two-dimensional geometries. For spatial backends that support it, it may be set to 3 for three-dimensional support.
Note
At this time 3D support is limited to the PostGIS spatial backend.
geography¶
-
GeometryField.geography¶
If set to True, this option will create a database column of
type geography, rather than geometry. Please refer to the
geography type section below for more
details.
Note
Geography support is limited to PostGIS and will force the SRID to be 4326.
Geography Type¶
The geography type provides native support for spatial features represented
with geographic coordinates (e.g., WGS84 longitude/latitude). [6]
Unlike the plane used by a geometry type, the geography type uses a spherical
representation of its data. Distance and measurement operations
performed on a geography column automatically employ great circle arc
calculations and return linear units. In other words, when ST_Distance
is called on two geographies, a value in meters is returned (as opposed
to degrees if called on a geometry column in WGS84).
Because geography calculations involve more mathematics, only a subset of the PostGIS spatial lookups are available for the geography type. Practically, this means that in addition to the distance lookups only the following additional spatial lookups are available for geography columns:
If you need to use a spatial lookup or aggregate that doesn’t support the
geography type as input, you can use the
Cast database function to convert the
geography column to a geometry type in the query:
from django.contrib.gis.db.models import PointField
from django.db.models.functions import Cast
Zipcode.objects.annotate(
geom=Cast('geography_field', PointField())
).filter(geom__within=poly)
For more information, the PostGIS documentation contains a helpful section on determining when to use geography data type over geometry data type.
GeoManager¶
The GeoManager is required in order to use the legacy
GeoQuerySet Methods.
Deprecated since version 1.9: All GeoQuerySet methods have been deprecated and replaced by
equivalent database functions. As soon
as the legacy methods have been replaced in your code, you should be able
to remove the special GeoManager from your GIS-enabled classes.
In older versions, the manager was required to conduct geographic queries. Without it, all geographic filters failed.
GeoManager was required even if the model did not have a geographic
field itself, e.g., in the case of a ForeignKey relation to a model
with a geographic field. For example, if we had an Address model with
a ForeignKey to our Zipcode model:
from django.contrib.gis.db import models
class Address(models.Model):
num = models.IntegerField()
street = models.CharField(max_length=100)
city = models.CharField(max_length=100)
state = models.CharField(max_length=2)
zipcode = models.ForeignKey(Zipcode, on_delete=models.CASCADE)
objects = models.GeoManager()
The geographic manager was needed to do spatial queries on related
Zipcode objects, for example:
qs = Address.objects.filter(zipcode__poly__contains='POINT(-104.590948 38.319914)')
Footnotes
| [1] | OpenGIS Consortium, Inc., Simple Feature Specification For SQL. |
| [2] | See id. at Ch. 2.3.8, p. 39 (Geometry Values and Spatial Reference Systems). |
| [3] | Typically, SRID integer corresponds to an EPSG (European Petroleum Survey Group) identifier. However, it may also be associated with custom projections defined in spatial database’s spatial reference systems table. |
| [4] | 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. |
| [5] | This limitation does not apply to PostGIS. |
| [6] | Please refer to the PostGIS Geography Type documentation for more details. |
