Changes between Initial Version and Version 1 of GeoDjangoDatabaseAPI

Timestamp:

Jun 2, 2007, 10:56:28 PM (17 years ago)

Author:

jbronn

Comment:

GeoDjango database api

GeoDjangoDatabaseAPI

@@ +1 @@
+[[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(<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):
+
+{{{
+#!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.