Changes between Version 4 and Version 5 of GeoDjangoDatabaseAPI


Ignore:
Timestamp:
Oct 22, 2007, 8:36:22 PM (17 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 =
Back to Top