Code

Changes between Version 14 and Version 15 of GeoDjangoDatabaseAPI


Ignore:
Timestamp:
02/11/08 11:19:13 (6 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.

Legend:

Unmodified
Added
Removed
Modified
  • GeoDjangoDatabaseAPI

    v14 v15  
    6565 
    6666== Distance Lookups == 
    67 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.   
    68  
    69 '''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.  
     67''Availability'': PostGIS, Oracle 
     68 
     69Distance lookups take a tuple parameter comprising: 
     70 1. A geometry to base calculations from; and  
     71 2. A number or `Distance` object containing the distance.   
     72 
     73If 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.   
     74 
     75'''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. 
    7076 
    7177The following distance lookups are available: 
     
    7682 * `distance_gte` 
    7783 
    78 For example, let's say we have a `City` model on a projected coordinate system: 
     84For 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: 
    7985{{{ 
    8086#!python 
    8187from django.contrib.gis.db import models 
    8288 
    83 class City(models.Model): 
     89class SouthTexasCity(models.Model): 
    8490    name = models.CharField(max_length=30) 
    85     point = models.PointField(srid=32140) # A projected coordinate system is used, units are in meters. 
     91    point = models.PointField(srid=32140) # A projected coordinate system (only valid for South Texas!) is used, units are in meters. 
    8692    objects = models.GeoManager() 
    8793}}} 
     
    9197>>> from django.contrib.gis.geos import * 
    9298>>> from django.contrib.gis.measure import D # `D` is a shortcut for `Distance` 
    93 >>> from geoapp import City  
     99>>> from geoapp import SouthTexasCity  
    94100>>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # Distances will be calculated from this point, which does _not_ have to be projected. 
    95 >>> qs = City.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed. 
    96 >>> qs = City.objects.filter(point__distance_lte=(pnt, D(km=7))) # Find all Cities w/in 7km of pnt 
    97 >>> qs = City.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt. 
    98 >>> qs = City.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported. 
     101>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed. 
     102>>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7))) # Find all Cities w/in 7km of pnt 
     103>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt. 
     104>>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported. 
    99105}}}  
    100106 
     
    235241''Availability'': PostGIS, Oracle 
    236242 
    237 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. 
     243The `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.   
     244 
     245In 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). 
     246{{{ 
     247>>> pnt = AustraliaCity.objects.get(name='Hobart').point # See django.contrib.gis.tests.distapp 
     248>>> for cty in AustraliaCity.objects.distance(pnt): print cty.name, cty.distance 
     249Wollongong 988817.397733 
     250Shellharbour 971590.470258 
     251Thirroul 1001051.96023 
     252Mittagong 974374.007691 
     253Batemans Bay 940359.188397 
     254Canberra 597578.655272 
     255Melbourne 574635.996781 
     256Sydney 1055625.32642 
     257Hobart 0.0 
     258Adelaide 1162133.07421 
     259}}}  
    238260 
    239261== extent ==