Changes between Version 7 and Version 8 of GeoDjangoDatabaseAPI

Timestamp:

Oct 30, 2007, 9:12:39 PM (17 years ago)

Author:

jbronn

Comment:

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

GeoDjangoDatabaseAPI

@@ -2 +2 @@
 = 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 [wiki:GeoDjangoModelAPI GeoDjango Model API docs]:
+'''Note:''' All !GeoDjango queries are performed via the `GeoQuerySet`, a modified version of Django's `QuerySet` that enables the construction of spatial SQL. 
+
+!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]):
 {{{
 #!python
@@ -185 +187 @@
    * MySQL equivalent `MBRTouches(g1, g2)` 
 
+= !GeoQuerySet Methods =
+
+== gml ==
+''Availability'': PostGIS, Oracle
+
+The `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.
+{{{
+>>> qs = Zip.objects.all().gml('poly')
+>>> print qs[0].gml
+<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
+}}}
+
+Keyword arguments:
+=== precision ===
+This 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.
+
+== kml ==
+
+''Availability'': PostGIS 1.2.1+
+
+The `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.
+
+{{{
+>>> qs = Zip.objects.all().kml('poly')
+>>> print qs[0].kml
+<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
+}}}
+
+Keyword arguments:
+=== precision ===
+This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8.
+
+== transform ==
+''Availability'': PostGIS, Oracle
+
+The `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.
+
+{{{
+>>> qs = Zip.objects.all().transform('poly') # Transforms to WGS84
+>>> qs = Zip.objects.all().transform('poly', 32140) # Transforming to "NAD83 / Texas South Central"
+>>> print qs[0].poly.srid
+32140
+>>> print qs[0].poly
+POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
+}}}
+
+Keyword arguments:
+=== srid ===
+The `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.
+
+== union ==
+''Availability'': PostGIS, Oracle
+
+This `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.
+
+{{{
+>>> u = Zip.objects.union('poly') # This may take a LONG time, but returns a geometry representing the union of all Zip code polygons.
+>>> u = Zip.objects.filter(poly__within=bbox).union('poly') # A more sensible approach.
+}}}
+
+Keyword arguments:
+=== tolerance ===
+This 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.
+
 = Extra Instance Methods =
 '''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.