[[TOC]] = 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 [GeoDjangoModelAPI GeoDjango Model API docs]: {{{ #!python >>> qs = Zip.objects.filter(__=) >>> 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): {{{ #!python >>> 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: * WKT Polygon: {{{'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'}}} * ''See'' Open GIS Consortium, Inc., ''[http://www.opengis.org/docs/99-049.pdf OpenGIS Simple Feature Specification For SQL]'', Document 99-049 (May 5, 1999), at Ch. 3.2.5 (SQL Textual Representation of Geometry, pg. 53). * HEXEWKB Polygon: '{{{0103000000010000000 ... 00000000000002440'}}} * ''See'' [http://postgis.refractions.net/docs/ch04.html#id2904792 "PostGIS EWKB, EWKT and Canonical Forms"], PostGIS documentation at Ch. 4.1.2. == PostGIS Operator Field Lookup Types == * ''See generally'', [http://postgis.refractions.net/docs/ch06.html#id2854381 "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'' [http://postgis.refractions.net/docs/ch06.html#id2615853 "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)}}} * {{{intersects}}} * PostGIS equivalent {{{Intersects(geometry, geometry)}}} * {{{touches}}} * PostGIS equivalent {{{Touches(geometry, geometry)}}} * {{{crosses}}} * PostGIS equivalent {{{Crosses(geometry, geometry)}}} * {{{overlaps}}} * PostGIS equivalent {{{Overlaps(geometry, geometry)}}} * {{{contains}}} * PostGIS equivalent {{{Contains(geometry, geometry)}}} * {{{intersects}}} * PostGIS equivalent {{{Intersects(geometry, geometry)}}} * {{{relate}}} * 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: == get_GEOM_ogr == Returns a {{{OGRGeometry}}} instance for the geometry. == get_GEOM_geos == Returns a {{{GEOSGeometry}}} instance for the geometry. For example (using the {{{District}}} model from above): {{{ #!python >>> from django.contrib.gis.geos import GEOSGeometry >>> 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_wkt == Returns the OGC WKT (Well Known Text) for the geometry. For example (using the {{{School}}} model from above): {{{ #!python >>> skool = School.objects.get(name='PSAS') >>> print skool.get_point_wkt() POINT(-95.460822 29.745463) }}} == get_GEOM_centroid == This routine will return the centroid of the geometry. For example (using the {{{District}}} model from above): {{{ #!python >>> dist = District.objects.get(name='Houston ISD') >>> print dist.get_poly_centroid() POINT(-95.231713 29.723235) }}} == get_GEOM_area == This routine will return the area of the geometry field. {{{ #!python >>> 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.