| 65 | |
| 66 | == 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 | The following distance lookups are available: |
| 70 | |
| 71 | * `distance_lt` |
| 72 | * `distance_lte` |
| 73 | * `distance_gt` |
| 74 | * `distance_gte` |
| 75 | |
| 76 | For example, let's say we have a `City` model on a projected coordinate system: |
| 77 | {{{ |
| 78 | #!python |
| 79 | from django.contrib.gis.db import models |
| 80 | |
| 81 | class City(models.Model): |
| 82 | name = models.CharField(max_length=30) |
| 83 | point = models.PointField(srid=32140) # A projected coordinate system is used, units are in meters. |
| 84 | objects = models.GeoManager() |
| 85 | }}} |
| 86 | Then distance queries may be performed as follows: |
| 87 | {{{ |
| 88 | #!python |
| 89 | >>> from django.contrib.gis.geos import * |
| 90 | >>> from django.contrib.gis.measure import D # `D` is a shortcut for `Distance` |
| 91 | >>> from geoapp import City |
| 92 | >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326) # Distances will be calculated from this point, which does _not_ have to be projected. |
| 93 | >>> qs = City.objects.filter(point__distance_lte=(pnt, 7000)) # If numeric parameter, units of field (meters in this case) are assumed. |
| 94 | >>> qs = City.objects.filter(point__distance_lte=(pnt, D(km=7))) # Find all Cities w/in 7km of pnt |
| 95 | >>> qs = City.objects.filter(point__distance_gte=(pnt, D(mi=20))) # Find all Cities > 20 miles away from pnt. |
| 96 | >>> qs = City.objects.filter(point__distance_gte=(pnt, D(chain=100))) # More obscure units, such as chains, are supported. |
| 97 | }}} |