Code

Changes between Version 7 and Version 8 of GeoDjangoDatabaseAPI


Ignore:
Timestamp:
10/30/07 19:12:39 (6 years ago)
Author:
jbronn
Comment:

Added documentation for the gml, kml, transform, and union queryset methods

Legend:

Unmodified
Added
Removed
Modified
  • GeoDjangoDatabaseAPI

    v7 v8  
    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:''' All !GeoDjango queries are performed via the `GeoQuerySet`, a modified version of Django's `QuerySet` that enables the construction of spatial SQL.  
     5 
     6!GeoDjango's 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]): 
    57{{{ 
    68#!python 
     
    185187   * MySQL equivalent `MBRTouches(g1, g2)`  
    186188 
     189= !GeoQuerySet Methods = 
     190 
     191== gml == 
     192''Availability'': PostGIS, Oracle 
     193 
     194The `gml` method takes the name of the geographic field (a string) as a parameter, and will attach a `gml` attribute to every model in the queryset that contains the [http://en.wikipedia.org/wiki/Geography_Markup_Language Geographic Markup Language] (GML) representation of the geometry. 
     195{{{ 
     196>>> qs = Zip.objects.all().gml('poly') 
     197>>> print qs[0].gml 
     198<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon> 
     199}}} 
     200 
     201Keyword arguments: 
     202=== precision === 
     203This keyword may be used to specify the number of significant digits for the coordinates in the GML representation -- the default value is 8.  This keyword may not be used on Oracle. 
     204 
     205== kml == 
     206 
     207''Availability'': PostGIS 1.2.1+ 
     208 
     209The `kml` method takes the name of the geographic field (a string) as a parameter, and will attach a `kml` attribute to every model in the queryset that contains the [http://code.google.com/apis/kml/documentation/ Keyhole Markup Language] (KML) representation of the geometry.  It should be noted that the contents of the KML are in WGS84, and will be transformed if necessary -- the geometry field attribute itself is not affected. 
     210 
     211{{{ 
     212>>> qs = Zip.objects.all().kml('poly') 
     213>>> print qs[0].kml 
     214<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon> 
     215}}} 
     216 
     217Keyword arguments: 
     218=== precision === 
     219This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8. 
     220 
     221== transform == 
     222''Availability'': PostGIS, Oracle 
     223 
     224The `transform` method takes the name of the geographic field (a string) as a parameter, and transforms the geometries to a different spatial refrence system.  If the `srid` keyword is not specified, WGS84 is used by default. 
     225 
     226{{{ 
     227>>> qs = Zip.objects.all().transform('poly') # Transforms to WGS84 
     228>>> qs = Zip.objects.all().transform('poly', 32140) # Transforming to "NAD83 / Texas South Central" 
     229>>> print qs[0].poly.srid 
     23032140 
     231>>> print qs[0].poly 
     232POLYGON ((234055.1698884720099159 4937796.9232223574072123 ... 
     233}}} 
     234 
     235Keyword arguments: 
     236=== srid === 
     237The `srid` keyword may be used to specify the spatial reference system identifier.  Please note that this may depend on your spatial database backend, ''e.g.'', those used for Oracle are not the same as those used by PostGIS. 
     238 
     239== union == 
     240''Availability'': PostGIS, Oracle 
     241 
     242This `union` method takes the name of the geographic field (a string) as a parameter, and returns a `GEOSGeometry` object comprising the union of every geometry in the queryset.  Please note that use of `union` is processor intensive and may take a significant amount of time on large querysets. 
     243 
     244{{{ 
     245>>> u = Zip.objects.union('poly') # This may take a LONG time, but returns a geometry representing the union of all Zip code polygons. 
     246>>> u = Zip.objects.filter(poly__within=bbox).union('poly') # A more sensible approach. 
     247}}} 
     248 
     249Keyword arguments: 
     250=== tolerance === 
     251This keyword is only available on Oracle platforms, and is for the tolerance value for `SDOAGGRTYPE`.  ''See'' the Oracle [http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 documentation] for more details. 
     252 
    187253= Extra Instance Methods = 
    188254'''Update:''' All of the extra instance methods haave been deprecated as of r6467 because lazy geometry support includes all of their functionality (including OGR geometries and OSR spatial references with the `ogr` and `srs` properties, respectively).  In other words, these properties may be directly accessed as attributes from the geometry field.