Changes between Version 8 and Version 9 of GeoDjangoDatabaseAPI

Timestamp:

Dec 4, 2007, 12:18:59 PM (16 years ago)

Author:

jbronn

Comment:

added stub about distance queries

GeoDjangoDatabaseAPI

@@ -63 +63 @@
  * HEXEWKB Polygon: '`0103000000010000000 ... 00000000000002440'`
    * ''See'' [http://postgis.refractions.net/docs/ch04.html#id2904792 "PostGIS EWKB, EWKT and Canonical Forms"], PostGIS documentation at Ch. 4.1.2. 
+
+== 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.  
+
+The following distance lookups are available:
+
+ * `distance_lt`
+ * `distance_lte`
+ * `distance_gt`
+ * `distance_gte`
+
+For example, let's say we have a `City` model on a projected coordinate system:
+{{{
+#!python
+from django.contrib.gis.db import models
+
+class City(models.Model):
+    name = models.CharField(max_length=30)
+    point = models.PointField(srid=32140) # A projected coordinate system is used, units are in meters.
+    objects = models.GeoManager()
+}}}
+Then distance queries may be performed as follows:
+{{{
+#!python
+>>> from django.contrib.gis.geos import *
+>>> from django.contrib.gis.measure import D # `D` is a shortcut for `Distance`
+>>> from geoapp import City 
+>>> 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.
+}}} 
 
 == PostGIS ==
@@ -156 +189 @@
  * `covers`
    * Oracle equivalent `SDO_COVERS(geometry1, geometry2)`
+ * `disjoint`
+   * Oracle equivalent `SDO_GEOM.RELATE(geometry1, 'DISJOINT', geometry2, 0.05)`
  * `dwithin`
    * Oracle equivalent `SDO_WITHIN_DISTANCE(geometry1, geometry2, 'distance=<param>')`