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 | |
| 69 | Distance 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 | |
| 73 | 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. |
| 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. |
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. |
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. |
| 243 | 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. |
| 244 | |
| 245 | 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). |
| 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 |
| 249 | Wollongong 988817.397733 |
| 250 | Shellharbour 971590.470258 |
| 251 | Thirroul 1001051.96023 |
| 252 | Mittagong 974374.007691 |
| 253 | Batemans Bay 940359.188397 |
| 254 | Canberra 597578.655272 |
| 255 | Melbourne 574635.996781 |
| 256 | Sydney 1055625.32642 |
| 257 | Hobart 0.0 |
| 258 | Adelaide 1162133.07421 |
| 259 | }}} |