Changes between Version 14 and Version 15 of GeoDjangoDatabaseAPI


Ignore:
Timestamp:
02/11/2008 01:19:13 PM (7 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 ==
Back to Top