GeoDjango currently provides the following spatial database backends:
django.contrib.gis.db.backends.postgis
django.contrib.gis.db.backends.mysql
django.contrib.gis.db.backends.oracle
django.contrib.gis.db.backends.spatialite
MySQL’s spatial extensions only support bounding box operations (what MySQL calls minimum bounding rectangles, or MBR). Specifically, MySQL does not conform to the OGC standard:
Currently, MySQL does not implement these functions [Contains
,Crosses
,Disjoint
,Intersects
,Overlaps
,Touches
,Within
] according to the specification. Those that are implemented return the same result as the corresponding MBR-based functions.
In other words, while spatial lookups such as contains
are available in GeoDjango when using MySQL, the results returned are really
equivalent to what would be returned when using bbcontains
on a different spatial backend.
Warning
True spatial indexes (R-trees) are only supported with MyISAM tables on MySQL. [5] In other words, when using MySQL spatial extensions you have to choose between fast spatial lookups and the integrity of your data – MyISAM tables do not support transactions or foreign key constraints.
RasterField
is currently only implemented for the PostGIS backend. Spatial
lookups are available for raster fields, but spatial database functions and
aggregates aren’t implemented for raster fields.
RasterField
now supports spatial lookups.
Here is an example of how to create a geometry object (assuming the Zipcode
model):
>>> from zipcode.models import Zipcode
>>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z.save()
GEOSGeometry
objects may also be used to save geometric models:
>>> from django.contrib.gis.geos import GEOSGeometry
>>> poly = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z = Zipcode(code=77096, poly=poly)
>>> z.save()
Moreover, if the GEOSGeometry
is in a different coordinate system (has a
different SRID value) than that of the field, then it will be implicitly
transformed into the SRID of the model’s field, using the spatial database’s
transform procedure:
>>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
>>> z = Zipcode(code=78212, poly=poly_3084)
>>> z.save()
>>> from django.db import connection
>>> print(connection.queries[-1]['sql']) # printing the last SQL statement executed (requires DEBUG=True)
INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
Thus, geometry parameters may be passed in using the GEOSGeometry
object, WKT
(Well Known Text [1]), HEXEWKB (PostGIS specific – a WKB geometry in
hexadecimal [2]), and GeoJSON [3] (requires GDAL). Essentially,
if the input is not a GEOSGeometry
object, the geometry field will attempt to
create a GEOSGeometry
instance from the input.
For more information creating GEOSGeometry
objects, refer to the GEOS tutorial.
When creating raster models, the raster field will implicitly convert the input
into a GDALRaster
using lazy-evaluation.
The raster field will therefore accept any input that is accepted by the
GDALRaster
constructor.
Here is an example of how to create a raster object from a raster file
volcano.tif
(assuming the Elevation
model):
>>> from elevation.models import Elevation
>>> dem = Elevation(name='Volcano', rast='/path/to/raster/volcano.tif')
>>> dem.save()
GDALRaster
objects may also be used to save
raster models:
>>> from django.contrib.gis.gdal import GDALRaster
>>> rast = GDALRaster({'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,
... 'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]})
>>> dem = Elevation(name='Canyon', rast=rast)
>>> dem.save()
Note that this equivalent to:
>>> dem = Elevation.objects.create(
... name='Canyon',
... rast={'width': 10, 'height': 10, 'name': 'Canyon', 'srid': 4326,
... 'scale': [0.1, -0.1], 'bands': [{"data": range(100)}]},
... )
GeoDjango’s lookup types may be used with any manager method like
filter()
, exclude()
, etc. However, the lookup types unique to
GeoDjango are only available on spatial fields.
Filters on ‘normal’ fields (e.g. CharField
)
may be chained with those on geographic fields. Geographic lookups accept
geometry and raster input on both sides and input types can be mixed freely.
The general structure of geographic lookups is described below. A complete reference can be found in the spatial lookup reference.
Geographic queries with geometries take the following general form (assuming
the Zipcode
model used in the GeoDjango Model API):
>>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
>>> qs = Zipcode.objects.exclude(...)
For example:
>>> qs = Zipcode.objects.filter(poly__contains=pnt)
>>> qs = Elevation.objects.filter(poly__contains=rst)
In this case, poly
is the geographic field, contains
is the spatial lookup type, pnt
is the parameter (which may be a
GEOSGeometry
object or a string of
GeoJSON , WKT, or HEXEWKB), and rst
is a
GDALRaster
object.
The raster lookup syntax is similar to the syntax for geometries. The only
difference is that a band index can be specified as additional input. If no band
index is specified, the first band is used by default (index 0
). In that
case the syntax is identical to the syntax for geometry lookups.
To specify the band index, an additional parameter can be specified on both sides of the lookup. On the left hand side, the double underscore syntax is used to pass a band index. On the right hand side, a tuple of the raster and band index can be specified.
This results in the following general form for lookups involving rasters
(assuming the Elevation
model used in the GeoDjango Model API):
>>> qs = Elevation.objects.filter(<field>__<lookup_type>=<parameter>)
>>> qs = Elevation.objects.filter(<field>__<band_index>__<lookup_type>=<parameter>)
>>> qs = Elevation.objects.filter(<field>__<lookup_type>=(<raster_input, <band_index>)
For example:
>>> qs = Elevation.objects.filter(rast__contains=geom)
>>> qs = Elevation.objects.filter(rast__contains=rst)
>>> qs = Elevation.objects.filter(rast__1__contains=geom)
>>> qs = Elevation.objects.filter(rast__contains=(rst, 1))
>>> qs = Elevation.objects.filter(rast__1__contains=(rst, 1))
On the left hand side of the example, rast
is the geographic raster field
and contains
is the spatial lookup type. On the right
hand side, geom
is a geometry input and rst
is a
GDALRaster
object. The band index defaults to
0
in the first two queries and is set to 1
on the others.
While all spatial lookups can be used with raster objects on both sides, not all underlying operators natively accept raster input. For cases where the operator expects geometry input, the raster is automatically converted to a geometry. It’s important to keep this in mind when interpreting the lookup results.
The type of raster support is listed for all lookups in the compatibility table. Lookups involving rasters are currently only available for the PostGIS backend.
Distance calculations with spatial data is tricky because, unfortunately, the Earth is not flat. Some distance queries with fields in a geographic coordinate system may have to be expressed differently because of limitations in PostGIS. Please see the Selecting an SRID section in the GeoDjango Model API documentation for more details.
Availability: PostGIS, Oracle, SpatiaLite, PGRaster (Native)
The following distance lookups are available:
Note
For measuring, rather than querying on distances, use the
Distance
function.
Distance lookups take a tuple parameter comprising:
Distance
object containing the distance.If a Distance
object is used,
it may be expressed in any units (the SQL generated will use units
converted to those of the field); otherwise, numeric parameters are assumed
to be in the units of the field.
Note
In PostGIS, ST_Distance_Sphere
does not limit the geometry types
geographic distance queries are performed with. [4] However,
these queries may take a long time, as great-circle distances must be
calculated on the fly for every row in the query. This is because the
spatial index on traditional geometry fields cannot be used.
For much better performance on WGS84 distance queries, consider using
geography columns in your database instead because
they are able to use their spatial index in distance queries.
You can tell GeoDjango to use a geography column by setting geography=True
in your field definition.
For example, let’s say we have a SouthTexasCity
model (from the
GeoDjango distance tests ) on a projected coordinate system valid for cities
in southern Texas:
from django.contrib.gis.db import models
class SouthTexasCity(models.Model):
name = models.CharField(max_length=30)
# A projected coordinate system (only valid for South Texas!)
# is used, units are in meters.
point = models.PointField(srid=32140)
Then distance queries may be performed as follows:
>>> from django.contrib.gis.geos import GEOSGeometry
>>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
>>> from geoapp.models import SouthTexasCity
# Distances will be calculated from this point, which does not have to be projected.
>>> pnt = GEOSGeometry('POINT(-96.876369 29.905320)', srid=4326)
# If numeric parameter, units of field (meters in this case) are assumed.
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
# Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
Raster queries work the same way by simply replacing the geometry field
point
with a raster field, or the pnt
object with a raster object, or
both. To specify the band index of a raster input on the right hand side, a
3-tuple can be passed to the lookup as follows:
>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(rst, 2, D(km=7)))
Where the band with index 2 (the third band) of the raster rst
would be
used for the lookup.
The following table provides a summary of what spatial lookups are available
for each spatial database backend. The PostGIS Raster (PGRaster) lookups are
divided into the three categories described in the raster lookup details: native support N
, bilateral native support B
,
and geometry conversion support C
.
Lookup Type | PostGIS | Oracle | MySQL [6] | SpatiaLite | PGRaster |
---|---|---|---|---|---|
bbcontains |
X | X | X | N | |
bboverlaps |
X | X | X | N | |
contained |
X | X | X | N | |
contains |
X | X | X | X | B |
contains_properly |
X | B | |||
coveredby |
X | X | B | ||
covers |
X | X | B | ||
crosses |
X | X | C | ||
disjoint |
X | X | X | X | B |
distance_gt |
X | X | X | N | |
distance_gte |
X | X | X | N | |
distance_lt |
X | X | X | N | |
distance_lte |
X | X | X | N | |
dwithin |
X | X | B | ||
equals |
X | X | X | X | C |
exact |
X | X | X | X | B |
intersects |
X | X | X | X | B |
isvalid |
X | ||||
overlaps |
X | X | X | X | B |
relate |
X | X | X | C | |
same_as |
X | X | X | X | B |
touches |
X | X | X | X | B |
within |
X | X | X | X | B |
left |
X | C | |||
right |
X | C | |||
overlaps_left |
X | B | |||
overlaps_right |
X | B | |||
overlaps_above |
X | C | |||
overlaps_below |
X | C | |||
strictly_above |
X | C | |||
strictly_below |
X | C |
The following table provides a summary of what geography-specific database functions are available on each spatial backend.
Function | PostGIS | Oracle | MySQL | SpatiaLite |
---|---|---|---|---|
Area |
X | X | X | X |
AsGeoJSON |
X | X | ||
AsGML |
X | X | ||
AsKML |
X | X | ||
AsSVG |
X | X | ||
BoundingCircle |
X | |||
Centroid |
X | X | X | X |
Difference |
X | X | X (≥ 5.6.1) | X |
Distance |
X | X | X (≥ 5.6.1) | X |
Envelope |
X | X | X | |
ForceRHR |
X | |||
GeoHash |
X | X (≥ 4.0, LWGEOM) | ||
Intersection |
X | X | X (≥ 5.6.1) | X |
IsValid |
X | |||
Length |
X | X | X | X |
MakeValid |
X | |||
MemSize |
X | |||
NumGeometries |
X | X | X | X |
NumPoints |
X | X | X | X |
Perimeter |
X | X | X (≥ 4.0) | |
PointOnSurface |
X | X | X | |
Reverse |
X | X | X (≥ 4.0) | |
Scale |
X | X | ||
SnapToGrid |
X | X (≥ 3.1) | ||
SymDifference |
X | X | X (≥ 5.6.1) | X |
Transform |
X | X | X | |
Translate |
X | X | ||
Union |
X | X | X (≥ 5.6.1) | X |
The following table provides a summary of what GIS-specific aggregate functions are available on each spatial backend. Please note that MySQL does not support any of these aggregates, and is thus excluded from the table.
Aggregate | PostGIS | Oracle | SpatiaLite |
---|---|---|---|
Collect |
X | X | |
Extent |
X | X | X |
Extent3D |
X | ||
MakeLine |
X | X | |
Union |
X | X | X |
Footnotes
[1] | See Open Geospatial Consortium, Inc., OpenGIS Simple Feature Specification For SQL, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry). |
[2] | See PostGIS EWKB, EWKT and Canonical Forms, PostGIS documentation at Ch. 4.1.2. |
[3] | See Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, The GeoJSON Format Specification, Revision 1.0 (June 16, 2008). |
[4] | See PostGIS documentation on ST_DistanceSphere . |
[5] | See Creating Spatial Indexes in the MySQL Reference Manual:
|
[6] | Refer MySQL Spatial Limitations section for more details. |
Jun 09, 2017