Changes between Version 4 and Version 5 of GeoDjangoDatabaseAPI
 Timestamp:
 10/22/07 20:36:22 (9 years ago)
Legend:
 Unmodified
 Added
 Removed
 Modified

GeoDjangoDatabaseAPI
v4 v5 2 2 = Database API = 3 3 4 '''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 [wiki:GeoDjangoModelAPI GeoDjango Model API docs]:4 '''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 [wiki:GeoDjangoModelAPI GeoDjango Model API docs]: 5 5 {{{ 6 6 #!python 7 >>> qs = Zip.objects.filter(< geo field A>__<geo lookup type>=<geo string B>)7 >>> qs = Zip.objects.filter(<field>__<lookup type>=<parameter>) 8 8 >>> qs = Zip.objects.exclude(...) 9 9 }}} 10 10 11 For example: 12 {{{ 13 #!python 14 >>> qs = Zip.objects.filter(poly__contains=pnt) 15 }}} 11 16 12 == Creating and Saving GeographicEnabled Objects == 13 Here is an example of how to create a geometry object (assuming the {{{Zip}}} model example above): 17 In this case, `poly` is the geographic field, `contains` is the lookup type, and `pnt` is the parameter (which may be a `GEOSGeometry` object, a string of WKT, or a string of HEXEWKB). 18 19 == Creating and Saving Geographic Models == 20 Here is an example of how to create a geometry object (assuming the `Zip` model): 14 21 15 22 {{{ … … 20 27 }}} 21 28 22 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: 23 * WKT Polygon: {{{'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'}}} 29 `GEOSGeometry` objects may also be used to save geometric models: 30 {{{ 31 #!python 32 >>> from django.contrib.gis.geos import GEOSGeometry 33 >>> z = Zip(code=77096, poly=GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')) 34 >>> z.save() 35 }}} 36 37 Moreover, if the `GEOSGeometry` is in a different coordinate system (has a different SRID value) than that of the field, then it will be implicitly transformed into the SRID of the model's field, using the spatial database's transform procedure: 38 {{{ 39 #!python 40 >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal' 41 >>> z = Zip(code=78212, poly=poly_3084) 42 >>> z.save() 43 >>> from django.db import connection 44 >>> print connection.queries[1]['sql'] # printing the last SQL statement executed 45 INSERT INTO "geoapp_zip" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326)) 46 }}} 47 48 Thus, geometry parameters may be passed in using the `GEOSGeometry` object, WKT (Well Known Text) or HEXEWKB (PostGIS specific, essentially a WKB geometry in hexadecimal). Essentially, if the input is not a `GEOSGeometry` object, it wFor example: 49 * GEOS Geometry: 50 {{{ 51 #!python 52 >>> from django.contrib.gis.geos import * 53 >>> pnt = Point(5, 23) 54 >>> ls = LineString((0, 0), (5, 23)) 55 >>> poly = GEOSGeometry('POLYGON (( 10 10, 10 20, 20 20, 20 15, 10 10))') 56 }}} 57 * WKT Polygon: `'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'` 24 58 * ''See'' Open GIS Consortium, Inc., ''[http://www.opengis.org/docs/99049.pdf OpenGIS Simple Feature Specification For SQL]'', Document 99049 (May 5, 1999), at Ch. 3.2.5 (SQL Textual Representation of Geometry, pg. 53). 25 * HEXEWKB Polygon: ' {{{0103000000010000000 ... 00000000000002440'}}}59 * HEXEWKB Polygon: '`0103000000010000000 ... 00000000000002440'` 26 60 * ''See'' [http://postgis.refractions.net/docs/ch04.html#id2904792 "PostGIS EWKB, EWKT and Canonical Forms"], PostGIS documentation at Ch. 4.1.2. 27 61 28 == PostGIS Operator Field Lookup Types==62 == PostGIS == 29 63 30 * ''See generally'', [http://postgis.refractions.net/docs/ch06.html#id2854381 "Operators", PostGIS Documentation at Ch. 6.2.2] 31 * '''Note:''' This API is subject to some change  we're open to suggestions. 32 * {{{overlaps_left}}} 64 === PostGIS Operator Field Lookup Types === 65 66 For more information, see generally, [http://postgis.refractions.net/docs/ch06.html#id2854381 "Operators", PostGIS Documentation at Ch. 6.2.2] 67 * `overlaps_left` 33 68 * Returns true if A's bounding box overlaps or is to the left of B's bounding box. 34 * PostGIS equivalent " {{{&<}}}"35 * {{{overlaps_right}}}69 * PostGIS equivalent "`&<`" 70 * `overlaps_right` 36 71 * Returns true if A's bounding box overlaps or is to the right of B's bounding box. 37 * PostGIS equivalent " {{{&>}}}"38 * {{{left}}}72 * PostGIS equivalent "`&>`" 73 * `left` 39 74 * Returns true if A's bounding box is strictly to the left of B's bounding box. 40 * PostGIS equivalent " {{{<<}}}"41 * {{{right}}}75 * PostGIS equivalent "`<<`" 76 * `right` 42 77 * Returns true if A's bounding box is strictly to the right of B's bounding box. 43 * PostGIS equivalent " {{{>>}}}"44 * {{{overlaps_below}}}78 * PostGIS equivalent "`>>`" 79 * `overlaps_below` 45 80 * Returns true if A's bounding box overlaps or is below B's bounding box. 46 * PostGIS equivalent " {{{&<}}}"47 * {{{overlaps_above}}}81 * PostGIS equivalent "`&<`" 82 * `overlaps_above` 48 83 * Returns true if A's bounding box overlaps or is above B's bounding box. 49 * PostGIS equivalent " {{{&>}}}"50 * {{{strictly_below}}}84 * PostGIS equivalent "`&>`" 85 * `strictly_below` 51 86 * Returns true if A's bounding box is strictly below B's bounding box. 52 * PostGIS equivalent " {{{<<}}}"53 * {{{strictly_above}}}87 * PostGIS equivalent "`<<`" 88 * `strictly_above` 54 89 * Returns true if A's bounding box is strictly above B's bounding box. 55 * PostGIS equivalent " {{{>>}}}"56 * {{{same_as}}} or {{{exact}}}90 * PostGIS equivalent "`>>`" 91 * `same_as` or `exact` 57 92 * The "same as" operator. It tests actual geometric equality of two features. So if A and B are the same feature, vertexbyvertex, the operator returns true. 58 * PostGIS equivalent " {{{~=}}}"59 * {{{contained}}}93 * PostGIS equivalent "`~=`" 94 * `contained` 60 95 * Returns true if A's bounding box is completely contained by B's bounding box. 61 * PostGIS equivalent " {{{@}}}"62 * {{{bbcontains}}}96 * PostGIS equivalent "`@`" 97 * `bbcontains` 63 98 * Returns true if A's bounding box completely contains B's bounding box. 64 * PostGIS equivalent " {{{~}}}"65 * {{{bboverlaps}}}99 * PostGIS equivalent "`~`" 100 * `bboverlaps` 66 101 * Returns true if A's bounding box overlaps B's bounding box. 67 * PostGIS equivalent " {{{&&}}}"102 * PostGIS equivalent "`&&`" 68 103 69 == PostGIS GEOS Function Field Lookup Types==70 * ''See generally'' [http://postgis.refractions.net/docs/ch06.html#id2615853 "Geometry Relationship Functions", PostGIS Documentation at Ch. 6.1.2]. 71 * This documentation will be updated completely with the content from the aforementioned PostGIS docs. 72 * {{{equals}}} 73 * Requires GEOS104 === PostGIS GEOS Function Field Lookup Types === 105 For more information, see generally [http://postgis.refractions.net/docs/ch06.html#id2615853 "Geometry Relationship Functions"], PostGIS Documentation at Ch. 6.1.2. 106 107 Please note that when using PostGIS 1.3.1 and above, index support is automatically "inlined"  in other words, the bounding box equivalent is automatically evaluated prior to calling these, more computationally expensive, functions. 108 * `equals` 74 109 * Returns 1 (TRUE) if the given Geometries are "spatially equal". 75 110 * Use this for a 'better' answer than '='. equals('LINESTRING(0 0, 10 10)','LINESTRING(0 0, 5 5, 10 10)') is true. 76 * PostGIS equivalent {{{Equals(geometry, geometry)}}}, OGC SPEC s2.1.1.2 77 * {{{disjoint}}} 78 * Requires GEOS 111 * PostGIS equivalent `Equals(geometry, geometry)`, OGC SPEC s2.1.1.2 112 * `disjoint` 79 113 * Returns 1 (TRUE) if the Geometries are "spatially disjoint". 80 * PostGIS equivalent {{{Disjoint(geometry, geometry)}}}81 * {{{touches}}}114 * PostGIS equivalent `Disjoint(geometry, geometry)` 115 * `touches` 82 116 * Returns 1 (TRUE) if the Geometries "spatially touch". 83 * PostGIS equivalent {{{Touches(geometry, geometry)}}}84 * {{{crosses}}}117 * PostGIS equivalent `Touches(geometry, geometry)` 118 * `crosses` 85 119 * Returns 1 (TRUE) if the Geometries "spatially cross". 86 * PostGIS equivalent {{{Crosses(geometry, geometry)}}}87 * {{{within}}}120 * PostGIS equivalent `Crosses(geometry, geometry)` 121 * `within` 88 122 * Returns 1 (TRUE) if Geometry A is "spatially within" Geometry B. 89 * PostGIS equivalent {{{Within(geometry, geometry)}}}90 * {{{overlaps}}}123 * PostGIS equivalent `Within(geometry, geometry)` 124 * `overlaps` 91 125 * Returns 1 (TRUE) if the Geometries "spatially overlap". 92 * PostGIS equivalent {{{Overlaps(geometry, geometry)}}}93 * {{{contains}}}126 * PostGIS equivalent `Overlaps(geometry, geometry)` 127 * `contains` 94 128 * Returns 1 (TRUE) if Geometry A "spatially contains" Geometry B. 95 * PostGIS equivalent {{{Contains(geometry, geometry)}}}96 * {{{relate}}}129 * PostGIS equivalent `Contains(geometry, geometry)` 130 * `relate` 97 131 * Returns the DE9IM (dimensionally extended nineintersection matrix) between the two geometries. 98 * PostGIS equivelent {{{Relate(geometry, geometry)}}} 132 * Tuple parameter `(geom, pattern)` required for lookup type, where `pattern` is an intersection pattern  a string comprising nine characters, where each character is one of `T`, `F`, or `*`.). 133 * PostGIS equivelent `Relate(geometry, geometry, intersectionPatternMatrix)` 134 135 The following lookup types are only available in PostGIS versions 1.3.1 and above: 136 * `dwithin` 137 * Returns true if geometries are within the specified distance of one another. Uses indexes if available. 138 * Tuple parameter `(geom, distance)` required for lookup type. 139 * `coveredby` 140 * Returns 1 (TRUE) if no point in Geometry A is outside Geometry B 141 * Refer to [http://linearthinking.blogspot.com/2007/06/subtletiesofogccoversspatial.html this resource] for an explaination of the need of this function. 142 * `covers` 143 * Returns 1 (TRUE) if no point in Geometry B is outside Geometry A 144 * See link in `coveredby` documentation above for more information. 145 146 == Oracle == 147 For more information, see generally, [http://download.oracle.com/docs/html/B14255_01/sdo_operat.htm Spatial Operators], Oracle Spatial User's Guide and Manual, at Ch. 11. 148 * `contains` 149 * Oracle equivalent `SDO_CONTAINS(geometry1, geometry2)` 150 * `coveredby` 151 * Oracle equivalent `SDO_COVEREDBY(geometry1, geometry2)` 152 * `covers` 153 * Oracle equivalent `SDO_COVERS(geometry1, geometry2)` 154 * `dwithin` 155 * Oracle equivalent `SDO_WITHIN_DISTANCE(geometry1, geometry2, 'distance=<param>')` 156 * Tuple parameter `(geom, distance)` required for lookup type. 157 * `equals`, `exact`, `same_as` 158 * Oracle equivalent, `SDO_EQUALS(geometry1, geometry2)` 159 * `intersects` 160 * Oracle equivalent `SDO_OVERLAPBDYINTERSECT(geometry1, geometry2)` 161 * `overlaps` 162 * Oracle equivalent `SDO_OVERLAPS(geometry1, geometry2)` 163 * `touches` 164 * Oracle equivalent `SDO_TOUCH(geometry1, geometry2)` 165 * `within` 166 * Oracle equivalent `SDO_INSIDE(geometry1, geometry2)` 167 168 == MySQL == 169 For more information, see generally, [http://dev.mysql.com/doc/refman/5.0/en/relationsongeometrymbr.html Relations on Geometry Minimal Bounding Rectangles (MBRs)], MySQL 5.0 Reference Manual, at Ch. 17.5.5. 170 * `bbcontains`, `contains` 171 * MySQL equivalent `MBRContains(g1, g2)` 172 * `contained`, `within` 173 * MySQL equivalent `MBRWithin(g1, g2)` 174 * `disjoint` 175 * MySQL equivalent `MBRDisjoint(g1, g2)` 176 * `equals`, `exact`, `same_as` 177 * MySQL equivalent `MBREqual(g1, g2)` 178 * `intersects` 179 * MySQL equivalent `MBRIntersects(g1, g2)` 180 * `overlaps` 181 * MySQL equivalent `MBROverlaps(g1, g2)` 182 * `touches` 183 * MySQL equivalent `MBRTouches(g1, g2)` 99 184 100 185 = Extra Instance Methods =