Version 1 (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 [GeoDjangoModelAPI 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)`

`intersects`- PostGIS equivalent
`Intersects(geometry, geometry)`

- PostGIS equivalent
`touches`- PostGIS equivalent
`Touches(geometry, geometry)`

- PostGIS equivalent
`crosses`- PostGIS equivalent
`Crosses(geometry, geometry)`

- PostGIS equivalent
`overlaps`- PostGIS equivalent
`Overlaps(geometry, geometry)`

- PostGIS equivalent
`contains`- PostGIS equivalent
`Contains(geometry, geometry)`

- PostGIS equivalent
`intersects`- PostGIS equivalent
`Intersects(geometry, geometry)`

- PostGIS equivalent
`relate`- PostGIS equivelent
`Relate(geometry, geometry)`

- PostGIS equivelent

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

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

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

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

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