Changes between Version 14 and Version 15 of GeoDjangoDatabaseAPI

Timestamp:

Feb 11, 2008, 1:19:13 PM (17 years ago)

Author:

jbronn

Comment:

Updated with information on geodetic distance support; clarified previous distance example, explicitly noting that the models is for South Texas; added example for the distance GeoQuerySet method.

GeoDjangoDatabaseAPI

@@ -65 +65 @@
 
 == Distance Lookups ==
-Distance lookups are supported on both PostGIS and Oracle.  Each distance lookup type takes a tuple parameter comprising (1) a geometry to base calculations from and (2) a number or `Distance` object containing the distance.  If a `Distance` object is used, it may be expressed in any units (the SQL generated will use units converted to those of the field); otherwise, numeric parameters will be assumed to be in the units of the field.  
-
-'''Note:''' The API currently only supports projected coordinate systems -- support for geodetic systems, such as WGS84 (the default projection for `GeometryField`), is in the works. ''See'' ticket #6414. 
+''Availability'': PostGIS, Oracle
+
+Distance lookups take a tuple parameter comprising:
+ 1. A geometry to base calculations from; and 
+ 2. A number or `Distance` object containing the distance.  
+
+If a `Distance` object is used, it may be expressed in any units (the SQL generated will use units converted to those of the field); otherwise, numeric parameters will be assumed to be in the units of the field.  
+
+'''Note:''' Distance lookups for geodetic coordinate systems was added in r7104 (fixing ticket #6414).  For those using Postgresql, the PostGIS routine `ST_distance_spheroid` is used -- which is limited to calculating distances only to/from points.  Thus, geodetic distance lookups on PostGIS are only allowed with `PointField`s using points as the geographic parameter.
 
 The following distance lookups are available:
@@ -76 +82 @@
  * `distance_gte`
 
-For example, let's say we have a `City` model on a projected coordinate system:
+For example, let's say we have a `SouthTexasCity` model (from [browser:django/branches/gis/django/contrib/gis/tests/distapp/models.py GeoDjango distance tests]) on a projected coordinate system valid for cities in southern Texas:
 {{{
 #!python
 from django.contrib.gis.db import models
 
-class City(models.Model):
+class SouthTexasCity(models.Model):
     name = models.CharField(max_length=30)
-    point = models.PointField(srid=32140) # A projected coordinate system is used, units are in meters.
+    point = models.PointField(srid=32140) # A projected coordinate system (only valid for South Texas!) is used, units are in meters.
     objects = models.GeoManager()
 }}}
@@ -91 +97 @@
 >>> from django.contrib.gis.geos import *
 >>> from django.contrib.gis.measure import D # `D` is a shortcut for `Distance`
->>> from geoapp import City 
+>>> from geoapp import SouthTexasCity 
 >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # Distances will be calculated from this point, which does _not_ have to be projected.
->>> qs = City.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed.
->>> qs = City.objects.filter(point__distance_lte=(pnt, D(km=7))) # Find all Cities w/in 7km of pnt
->>> qs = City.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt.
->>> qs = City.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported.
+>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed.
+>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7))) # Find all Cities w/in 7km of pnt
+>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt.
+>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported.
 }}} 
 
@@ -235 +241 @@
 ''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.
+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.  If a geodetic coordinate system is used (like WGS84), then the `distance` attribute will be in meters.  
+
+In the following example (from [browser:django/branches/gis/django/contrib/gis/tests/distapp GeoDjango distance tests]), the distance from the Tasmanian city of Hobart to every other `PointField` in the `AustraliaCity` queryset will be calculated.  The `distance` attribute is in meters because the `AustraliaCity` [browser:django/branches/gis/django/contrib/gis/tests/distapp/models.py model] uses WGS84 (the default when no SRID is specified via the `srid` keyword).
+{{{
+>>> pnt = AustraliaCity.objects.get(name='Hobart').point # See django.contrib.gis.tests.distapp
+>>> for cty in AustraliaCity.objects.distance(pnt): print cty.name, cty.distance
+Wollongong 988817.397733
+Shellharbour 971590.470258
+Thirroul 1001051.96023
+Mittagong 974374.007691
+Batemans Bay 940359.188397
+Canberra 597578.655272
+Melbourne 574635.996781
+Sydney 1055625.32642
+Hobart 0.0
+Adelaide 1162133.07421
+}}} 
 
 == extent ==