Version 4 (modified by jbronn, 9 years ago) (diff) |
---|

# 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:

- WKT Polygon:
`'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'`*See*Open GIS Consortium, Inc.,*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*PostGIS EWKB, EWKT and Canonical Forms, PostGIS documentation at Ch. 4.1.2.

## 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

**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.