Version 3 (modified by jbronn, 17 years ago) ( diff )

updated with info about deprecated extra instance methods

TOC(GeoDjangoDatabaseAPI)

Database API

Note: The following database lookup types can only be used with on geographic fields with filter(). Filters on 'normal' fields (e.g. CharField) may be chained with those on geographic fields. Thus, geographic queries take the following form (assuming the Zip model used in the GeoDjango Model API docs: 

>>> qs = Zip.objects.filter(<geo field A>__<geo lookup type>=<geo string B>)
>>> qs = Zip.objects.exclude(...)

Creating and Saving Geographic-Enabled Objects

Here is an example of how to create a geometry object (assuming the Zip model example above): 

>>> from zipcode.models import Zip
>>> z = Zip(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
>>> z.save()

Geometries are represented as strings in either of the formats WKT (Well Known Text) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). For example:

PostGIS Operator Field Lookup Types

  • See generally, ​"Operators", PostGIS Documentation at Ch. 6.2.2
  • Note: This API is subject to some change -- we're open to suggestions.
  • overlaps_left
    • Returns true if A's bounding box overlaps or is to the left of B's bounding box.
    • PostGIS equivalent "&<"
  • overlaps_right
    • Returns true if A's bounding box overlaps or is to the right of B's bounding box.
    • PostGIS equivalent "&>"
  • left
    • Returns true if A's bounding box is strictly to the left of B's bounding box.
    • PostGIS equivalent "<<"
  • right
    • Returns true if A's bounding box is strictly to the right of B's bounding box.
    • PostGIS equivalent ">>"
  • overlaps_below
    • Returns true if A's bounding box overlaps or is below B's bounding box.
    • PostGIS equivalent "&<|"
  • overlaps_above
    • Returns true if A's bounding box overlaps or is above B's bounding box.
    • PostGIS equivalent "|&>"
  • strictly_below
    • Returns true if A's bounding box is strictly below B's bounding box.
    • PostGIS equivalent "<<|"
  • strictly_above
    • Returns true if A's bounding box is strictly above B's bounding box.
    • PostGIS equivalent "|>>"
  • same_as or exact
    • The "same as" operator. It tests actual geometric equality of two features. So if A and B are the same feature, vertex-by-vertex, the operator returns true.
    • PostGIS equivalent "~="
  • contained
    • Returns true if A's bounding box is completely contained by B's bounding box.
    • PostGIS equivalent "@"
  • bbcontains
    • Returns true if A's bounding box completely contains B's bounding box.
    • PostGIS equivalent "~"
  • bboverlaps
    • Returns true if A's bounding box overlaps B's bounding box.
    • PostGIS equivalent "&&"

PostGIS GEOS Function Field Lookup Types

  • See generally ​"Geometry Relationship Functions", PostGIS Documentation at Ch. 6.1.2.
  • This documentation will be updated completely with the content from the aforementioned PostGIS docs.
  • equals
    • Requires GEOS
    • Returns 1 (TRUE) if the given Geometries are "spatially equal".
    • Use this for a 'better' answer than '='. equals('LINESTRING(0 0, 10 10)','LINESTRING(0 0, 5 5, 10 10)') is true.
    • PostGIS equivalent Equals(geometry, geometry), OGC SPEC s2.1.1.2
  • disjoint
    • Requires GEOS
    • Returns 1 (TRUE) if the Geometries are "spatially disjoint".
    • PostGIS equivalent Disjoint(geometry, geometry)
  • touches
    • Returns 1 (TRUE) if the Geometries "spatially touch".
    • PostGIS equivalent Touches(geometry, geometry)
  • crosses
    • Returns 1 (TRUE) if the Geometries "spatially cross".
    • PostGIS equivalent Crosses(geometry, geometry)
  • within
    • Returns 1 (TRUE) if Geometry A is "spatially within" Geometry B.
    • PostGIS equivalent Within(geometry, geometry)
  • overlaps
    • Returns 1 (TRUE) if the Geometries "spatially overlap".
    • PostGIS equivalent Overlaps(geometry, geometry)
  • contains
    • Returns 1 (TRUE) if Geometry A "spatially contains" Geometry B.
    • PostGIS equivalent Contains(geometry, geometry)
  • relate
    • Returns the DE-9IM (dimensionally extended nine-intersection matrix) between the two geometries.
    • PostGIS equivelent Relate(geometry, geometry)

Extra Instance Methods

A model with geometry fields will get the following methods, substitute GEOM with the name of the geometry field.

Update: All of the extra instance methods below (except get_GEOM_ogr and get_GEOM_srs) have been deprecated in r5657 due to lazy geometry support. In other words, these properties may be directly accessed as attributes from the geometry field. As part of the deprecation process, ​warnings are issued when such methods are invoked so that users have notice to change their code before these methods disappear in the future.

get_GEOM_ogr

Returns a OGRGeometry instance for the geometry. For example, using the Zip model, as above: 

>>> from django.contrib.gis.gdal import OGRGeometry # Where to import from
>>> z = Zip.objects.get(code='77096')
>>> geom = z.get_poly_ogr()
>>> print geom
POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))
>>> for ring in poly:
...    print ring
...    for point in ring:
...        print point
...
LINEARRING (10 10,10 20,20 20,20 15,10 10)
(10.0, 10.0)
(10.0, 20.0)
(20.0, 20.0)
(20.0, 15.0)
(10.0, 10.0)

get_GEOM_srs

Returns the OGR SpatialReference object for this geometry. 

>>> from django.contrib.gis.gdal import SpatialReference # Where these related classes reside
>>> z = Zip.objects.get(code='77096')
>>> srs = z.get_poly_srs()
>>> print srs
GEOGCS["WGS 84",
    DATUM["WGS_1984",
        SPHEROID["WGS 84",6378137,298.257223563,
            AUTHORITY["EPSG","7030"]],
        TOWGS84[0,0,0,0,0,0,0],
        AUTHORITY["EPSG","6326"]],
    PRIMEM["Greenwich",0,
        AUTHORITY["EPSG","8901"]],
    UNIT["degree",0.01745329251994328,
        AUTHORITY["EPSG","9122"]],
    AUTHORITY["EPSG","4326"]]
>>> print srs.semi_major, srs.semi_minor, srs.inverse_flattening
6378137.0 6356752.31425 298.257223563
>>> print srs.geographic
True

get_GEOM_geos

Update: This extra instance method was deprecated in r5657 -- and may now be accessed directly through the attribute name of the geometry field -- e.g., dist.poly returns a GEOSGeometry instance for the PolygonField of the District model.

Returns a GEOSGeometry instance for the geometry. For example (using the District model from the example): 

>>> from django.contrib.gis.geos import GEOSGeometry # Where to import from
>>> dist = District.objects.get(name='Houston ISD')
>>> geom = dist.get_poly_geos()
>>> print geom.centroid.wkt
POINT(-95.231713 29.723235)
>>> print geom.area
0.08332
>>> print geom.geom_type
Polygon
>>> print geom.centroid.geom_type
Point
>>> print geom.intersects(GEOSGeometry('POINT(-95.395223 29.798088)'))
False

get_GEOM_srid

Update: This extra instance method was deprecated in r5657 -- and may now be accessed directly through the attribute name of the geometry field -- e.g., dist.poly.srid.

Returns the SRID (source reference identifier) for the geometry.

get_GEOM_wkt

Update: This extra instance method was deprecated in r5657 -- and may now be accessed directly through the attribute name of the geometry field -- e.g., skool.point.wkt, or simply str(skool.point).

Returns the OGC WKT (Well Known Text) for the geometry. For example (using the School model from the example): 

>>> skool = School.objects.get(name='PSAS')
>>> print skool.get_point_wkt()
POINT(-95.460822 29.745463)

get_GEOM_centroid

Update: This extra instance method was deprecated in r5657 -- and may now be accessed directly through the attribute name of the geometry field -- e.g., dist.poly.centroid.wkt.

This routine will return the centroid of the geometry. For example (using the District model from above): 

>>> dist = District.objects.get(name='Houston ISD')
>>> print dist.get_poly_centroid()
POINT(-95.231713 29.723235)

get_GEOM_area

Update: This extra instance method was deprecated in r5657 -- and may now be accessed directly through the attribute name of the geometry field -- e.g., dist.poly.area.

This routine will return the area of the geometry field. 

>>> dist = District.objects.get(name='Houston ISD')
>>> print dist.get_poly_area()
0.08332

Note: Units are in the projected units of the coordinate system. In the example above, the units are in degrees since we're using WGS84.

Note: See TracWiki for help on using the wiki.
Back to Top