Note: All GeoDjango queries are performed via the GeoQuerySet, a modified version of Django's QuerySet that enables the construction of spatial SQL.
In this case, poly is the geographic field, contains is the lookup type, and pnt is the parameter (which may be a GEOSGeometry object, a string of WKT, or a string of HEXEWKB).
Thus, geometry parameters may be passed in using the GEOSGeometry object, WKT (Well Known Text) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). Essentially, if the input is not a GEOSGeometry object, it will attempt to instantiate a GEOSGeometry object from the input.
Below are some examples and references for GEOS Geometry objects, WKT, and HEXEWKB.
Distance lookups are supported on both PostGIS and Oracle. Each distance lookup type takes a tuple parameter comprising (1) a geometry to base calculations from and (2) a number or 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 will be assumed to be in the units of the field.
point = models.PointField(srid=32140) # A projected coordinate system is used, units are in meters.
>>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # Distances will be calculated from this point, which does _not_ have to be projected.
>>> qs = City.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed.
>>> qs = City.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt.
>>> qs = City.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported.
For more information, see generally ​Geometry Relationship Functions, PostGIS Documentation at Ch. 6.1.2.
Please note that when using PostGIS 1.3.1 and above, index support is automatically "inlined" -- in other words, the bounding box equivalent is automatically evaluated prior to calling these, more computationally expensive, functions.
Returns 1 (TRUE) if the Geometries "spatially touch".
Returns 1 (TRUE) if the Geometries "spatially cross".
Returns 1 (TRUE) if Geometry A is "spatially within" Geometry B.
Returns 1 (TRUE) if the Geometries "spatially overlap".
Returns 1 (TRUE) if Geometry A "spatially contains" Geometry B.
Returns the DE-9IM (dimensionally extended nine-intersection matrix) between the two geometries.
Tuple parameter (geom, pattern) required for lookup type, where pattern is an intersection pattern -- a string comprising nine characters, where each character is one of T, F, or *.).
Returns true if geometries are within the specified distance of one another. Uses indexes if available.
Tuple parameter (geom, distance) required for lookup type.
Refer to ​this resource for an explaination of the need of this function.
See link in coveredby documentation above for more information.
For more information, see generally, ​Spatial Operators, Oracle Spatial User's Guide and Manual, at Ch. 11.
For more information, see generally, ​Relations on Geometry Minimal Bounding Rectangles (MBRs), MySQL 5.0 Reference Manual, at Ch. 17.5.5.
The gml method takes the name of the geographic field (a string) as a parameter, and will attach a gml attribute to every model in the queryset that contains the ​Geographic Markup Language (GML) representation of the geometry.
This keyword may be used to specify the number of significant digits for the coordinates in the GML representation -- the default value is 8. This keyword may not be used on Oracle.
The kml method takes the name of the geographic field (a string) as a parameter, and will attach a kml attribute to every model in the queryset that contains the ​Keyhole Markup Language (KML) representation of the geometry. It should be noted that the contents of the KML are in WGS84, and will be transformed if necessary -- the geometry field attribute itself is not affected.
This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8.
The transform method takes the name of the geographic field (a string) as a parameter, and transforms the geometries to a different spatial refrence system. If the srid keyword is not specified, WGS84 is used by default.
>>> qs = Zip.objects.all().transform('poly', 32140) # Transforming to "NAD83 / Texas South Central"
The srid keyword may be used to specify the spatial reference system identifier. Please note that this may depend on your spatial database backend, e.g., those used for Oracle are not the same as those used by PostGIS.
This union method takes the name of the geographic field (a string) as a parameter, and returns a GEOSGeometry object comprising the union of every geometry in the queryset. Please note that use of union is processor intensive and may take a significant amount of time on large querysets.
>>> u = Zip.objects.union('poly') # This may take a LONG time, but returns a geometry representing the union of all Zip code polygons.
>>> u = Zip.objects.filter(poly__within=bbox).union('poly') # A more sensible approach.
This keyword is only available on Oracle platforms, and is for the tolerance value for SDOAGGRTYPE. See the Oracle ​documentation for more details.
Update: All of the extra instance methods haave been deprecated as of r6467 because lazy geometry support includes all of their functionality (including OGR geometries and OSR spatial references with the ogr and srs properties, respectively). In other words, these properties may be directly accessed as attributes from the geometry field.