Version 2 (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

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

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

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

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

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

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.