Changes between Version 9 and Version 10 of GeoDjangoDatabaseAPI

Timestamp:

Dec 8, 2007, 10:08:30 PM (16 years ago)

Author:

jbronn

Comment:

added distance stub; updated queryset manager method usage.

GeoDjangoDatabaseAPI

@@ -224 +224 @@
 = !GeoQuerySet Methods =
 
+'''Note:''' All of these methods may take an optional `field_name` keyword parameter that will specify the field on the model to perform the method on.  If no field name is specified, then the first geographic field encountered in the model will be assumed.
+
+== distance ==
+''Availability'': PostGIS, Oracle
+The `distance` method takes a geometry as a parameter, and will attach a `distance` attribute to every model in the returned queryset that contains the distance (in units of the field) to the given geometry.
+
 == 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')
+The `gml` method attaches 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()
 >>> print qs[0].gml
 <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
@@ -242 +248 @@
 ''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')
+The `kml` method attaches 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()
 >>> print qs[0].kml
 <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
@@ -257 +263 @@
 ''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"
+The `transform` method transforms the geometries in a model to a different spatial reference system.  If the `srid` parameter is not specified, WGS84 is used by default.
+
+{{{
+>>> qs = Zip.objects.all().transform() # Transforms to WGS84
+>>> qs = Zip.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
 >>> print qs[0].poly.srid
 32140
@@ -275 +281 @@
 ''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.
+This `union` method 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() # 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() # A more sensible approach.
 }}}