Code

Changes between Version 4 and Version 5 of GeoDjangoDatabaseAPI


Ignore:
Timestamp:
10/22/07 18:36:22 (7 years ago)
Author:
jbronn
Comment:

Updated with Oracle & MySQL APIs, tried to clean up and give more examples.

Legend:

Unmodified
Added
Removed
Modified
  • GeoDjangoDatabaseAPI

    v4 v5  
    22= Database API = 
    33 
    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]: 
    55{{{ 
    66#!python 
    7 >>> qs = Zip.objects.filter(<geo field A>__<geo lookup type>=<geo string B>) 
     7>>> qs = Zip.objects.filter(<field>__<lookup type>=<parameter>) 
    88>>> qs = Zip.objects.exclude(...) 
    99}}} 
    1010 
     11For example: 
     12{{{ 
     13#!python 
     14>>> qs = Zip.objects.filter(poly__contains=pnt) 
     15}}} 
    1116 
    12 == Creating and Saving Geographic-Enabled Objects == 
    13 Here is an example of how to create a geometry object (assuming the {{{Zip}}} model example above): 
     17In 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 == 
     20Here is an example of how to create a geometry object (assuming the `Zip` model): 
    1421 
    1522{{{ 
     
    2027}}} 
    2128 
    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 
     37Moreover, 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 
     45INSERT INTO "geoapp_zip" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326)) 
     46}}} 
     47 
     48Thus, 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))'` 
    2458   * ''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). 
    25  * HEXEWKB Polygon: '{{{0103000000010000000 ... 00000000000002440'}}} 
     59 * HEXEWKB Polygon: '`0103000000010000000 ... 00000000000002440'` 
    2660   * ''See'' [http://postgis.refractions.net/docs/ch04.html#id2904792 "PostGIS EWKB, EWKT and Canonical Forms"], PostGIS documentation at Ch. 4.1.2.  
    2761 
    28 == PostGIS Operator Field Lookup Types == 
     62== PostGIS == 
    2963 
    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 
     66For more information, see generally, [http://postgis.refractions.net/docs/ch06.html#id2854381 "Operators", PostGIS Documentation at Ch. 6.2.2] 
     67 * `overlaps_left` 
    3368   * 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`  
    3671   * 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` 
    3974   * 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` 
    4277   * 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` 
    4580   * 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` 
    4883   * 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` 
    5186   * 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` 
    5489   * 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` 
    5792   * 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. 
    58    * PostGIS equivalent "{{{~=}}}" 
    59  * {{{contained}}} 
     93   * PostGIS equivalent "`~=`" 
     94 * `contained` 
    6095   * 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`  
    6398   * Returns true if A's bounding box completely contains B's bounding box. 
    64    * PostGIS equivalent "{{{~}}}" 
    65  * {{{bboverlaps}}} 
     99   * PostGIS equivalent "`~`" 
     100 * `bboverlaps` 
    66101   * Returns true if A's bounding box overlaps B's bounding box. 
    67    * PostGIS equivalent "{{{&&}}}" 
     102   * PostGIS equivalent "`&&`" 
    68103 
    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 GEOS 
     104=== PostGIS GEOS Function Field Lookup Types === 
     105For more information, see generally [http://postgis.refractions.net/docs/ch06.html#id2615853 "Geometry Relationship Functions"], PostGIS Documentation at Ch. 6.1.2. 
     106 
     107Please 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` 
    74109   * Returns 1 (TRUE) if the given Geometries are "spatially equal".  
    75110   * 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` 
    79113   * 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` 
    82116   * Returns 1 (TRUE) if the Geometries "spatially touch". 
    83    * PostGIS equivalent {{{Touches(geometry, geometry)}}} 
    84  * {{{crosses}}} 
     117   * PostGIS equivalent `Touches(geometry, geometry)` 
     118 * `crosses` 
    85119   * Returns 1 (TRUE) if the Geometries "spatially cross". 
    86    * PostGIS equivalent {{{Crosses(geometry, geometry)}}} 
    87  * {{{within}}} 
     120   * PostGIS equivalent `Crosses(geometry, geometry)` 
     121 * `within` 
    88122   * 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` 
    91125   * Returns 1 (TRUE) if the Geometries "spatially overlap". 
    92    * PostGIS equivalent {{{Overlaps(geometry, geometry)}}} 
    93  * {{{contains}}} 
     126   * PostGIS equivalent `Overlaps(geometry, geometry)` 
     127 * `contains` 
    94128   * 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` 
    97131   * Returns the DE-9IM (dimensionally extended nine-intersection 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 
     135The 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://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.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 == 
     147For 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 == 
     169For more information, see generally, [http://dev.mysql.com/doc/refman/5.0/en/relations-on-geometry-mbr.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)`  
    99184 
    100185= Extra Instance Methods =