1 | ======================
|
---|
2 | GeoDjango Database API
|
---|
3 | ======================
|
---|
4 |
|
---|
5 | .. currentmodule:: django.contrib.gis.db.models
|
---|
6 |
|
---|
7 | GeoDjango's lookup types may be used with any manager method like
|
---|
8 | ``filter()``, ``exclude()``, etc. However, the lookup types unique to
|
---|
9 | GeoDjango are only available with geographic fields.
|
---|
10 | Filters on 'normal' fields (e.g. ``CharField``) may be chained with those on
|
---|
11 | geographic fields. Thus, geographic queries take the following form (assuming
|
---|
12 | the ``Zipcode`` model used in the `GeoDjango Model API`_)::
|
---|
13 |
|
---|
14 | >>> qs = Zipcode.objects.filter(<field>__<lookup_type>=<parameter>)
|
---|
15 | >>> qs = Zipcode.objects.exclude(...)
|
---|
16 |
|
---|
17 | For example::
|
---|
18 |
|
---|
19 | >>> qs = Zipcode.objects.filter(poly__contains=pnt)
|
---|
20 |
|
---|
21 | In this case, ``poly`` is the geographic field, ``contains`` is the lookup type,
|
---|
22 | and ``pnt`` is the parameter (which may be a ``GEOSGeometry`` object or a string
|
---|
23 | of GeoJSON , WKT, or HEXEWKB).
|
---|
24 |
|
---|
25 | .. note::
|
---|
26 |
|
---|
27 | GeoDjango constructs spatial SQL with the ``GeoQuerySet``, a
|
---|
28 | subclass of Django's ``QuerySet``. The ``GeoManager`` instance
|
---|
29 | attached to your model allows it to use ``GeoQuerySet``.
|
---|
30 |
|
---|
31 | .. _GeoDjango Model API: model-api.html
|
---|
32 |
|
---|
33 | Creating and Saving Geographic Models
|
---|
34 | =====================================
|
---|
35 | Here is an example of how to create a geometry object (assuming the ``Zipcode``
|
---|
36 | model)::
|
---|
37 |
|
---|
38 | >>> from zipcode.models import Zipcode
|
---|
39 | >>> z = Zipcode(code=77096, poly='POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))')
|
---|
40 | >>> z.save()
|
---|
41 |
|
---|
42 | `GEOS geometry objects`_ may also be used to save geometric models::
|
---|
43 |
|
---|
44 | >>> from django.contrib.gis.geos import GEOSGeometry
|
---|
45 | >>> z = Zipcode(code=77096, poly=GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'))
|
---|
46 | >>> z.save()
|
---|
47 |
|
---|
48 | Moreover, if the ``GEOSGeometry`` is in a different coordinate system (has a
|
---|
49 | different SRID value) than that of the field, then it will be implicitly
|
---|
50 | transformed into the SRID of the model's field, using the spatial database's
|
---|
51 | transform procedure::
|
---|
52 |
|
---|
53 | >>> poly_3084 = GEOSGeometry('POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))', srid=3084) # SRID 3084 is 'NAD83(HARN) / Texas Centric Lambert Conformal'
|
---|
54 | >>> z = Zipcode(code=78212, poly=poly_3084)
|
---|
55 | >>> z.save()
|
---|
56 | >>> from django.db import connection
|
---|
57 | >>> print connection.queries[-1]['sql'] # printing the last SQL statement executed (requires DEBUG=True)
|
---|
58 | INSERT INTO "geoapp_zipcode" ("code", "poly") VALUES (78212, ST_Transform(ST_GeomFromWKB('\\001 ... ', 3084), 4326))
|
---|
59 |
|
---|
60 | Thus, geometry parameters may be passed in using the ``GEOSGeometry`` object, WKT
|
---|
61 | (Well Known Text [#]_), HEXEWKB (PostGIS specific -- a WKB geometry in
|
---|
62 | hexadecimal [#]_), and GeoJSON [#]_ (requires GDAL). Essentially, if the input is not a
|
---|
63 | ``GEOSGeometry`` object, the geometry field will attempt to create a ``GEOSGeometry``
|
---|
64 | instance from the input.
|
---|
65 |
|
---|
66 | Below are some examples of GEOS Geometry objects, WKT, and HEXEWKB, and
|
---|
67 | GeoJSON:
|
---|
68 |
|
---|
69 | * GEOS Geometry::
|
---|
70 |
|
---|
71 | >>> from django.contrib.gis.geos import *
|
---|
72 | >>> pnt = Point(5, 23)
|
---|
73 | >>> ls = LineString((0, 0), (5, 23))
|
---|
74 | >>> poly = GEOSGeometry('POLYGON (( 10 10, 10 20, 20 20, 20 15, 10 10))')
|
---|
75 |
|
---|
76 | * WKT Polygon: ``'POLYGON(( 10 10, 10 20, 20 20, 20 15, 10 10))'``
|
---|
77 | * HEXEWKB Polygon : ``'0103000000010000000 ... 00000000000002440'``
|
---|
78 | * GeoJSON Point: ``{ "type": "Point", "coordinates": [100.0, 0.0] }``
|
---|
79 |
|
---|
80 | .. _GEOS geometry objects: geos.html
|
---|
81 |
|
---|
82 | Spatial Lookup Types
|
---|
83 | ====================
|
---|
84 |
|
---|
85 | PostGIS
|
---|
86 | -------
|
---|
87 |
|
---|
88 | Spatial Operators
|
---|
89 | ^^^^^^^^^^^^^^^^^
|
---|
90 |
|
---|
91 | The following lookup types correspond to PostGIS spatial operators. [#]_
|
---|
92 |
|
---|
93 | :lookup:`bbcontains`
|
---|
94 | Tests if the geometry field's bounding box completely contains the lookup
|
---|
95 | geometry's bounding box.
|
---|
96 |
|
---|
97 | Example::
|
---|
98 |
|
---|
99 | Zipcode.objects.filter(poly__bbcontains=geom)
|
---|
100 |
|
---|
101 | PostGIS equivalent::
|
---|
102 |
|
---|
103 | SELECT ... WHERE poly ~ geom
|
---|
104 |
|
---|
105 | :lookup:`bboverlaps`
|
---|
106 | Tests if the geometry field's bounding box overlaps the lookup geometry's
|
---|
107 | bounding box.
|
---|
108 |
|
---|
109 | Example::
|
---|
110 |
|
---|
111 | Zipcode.objects.filter(poly__bboverlaps=geom)
|
---|
112 |
|
---|
113 | PostGIS equivalent::
|
---|
114 |
|
---|
115 | SELECT ... WHERE poly && geom
|
---|
116 |
|
---|
117 | :lookup:`contained`
|
---|
118 | Tests if the geometry field's bounding box is completely contained by the
|
---|
119 | lookup geometry's bounding box.
|
---|
120 |
|
---|
121 | Example::
|
---|
122 |
|
---|
123 | Zipcode.objects.filter(poly__contained=geom)
|
---|
124 |
|
---|
125 | PostGIS equivalent::
|
---|
126 |
|
---|
127 | SELECT ... WHERE poly @ geom
|
---|
128 |
|
---|
129 | :lookup:`exact` or :lookup:`same_as`
|
---|
130 | Tests actual geometric equality of the geometry field against the the given
|
---|
131 | lookup geometry, vertex-by-vertex.
|
---|
132 |
|
---|
133 | The following examples are equivalent::
|
---|
134 |
|
---|
135 | Zipcode.objects.filter(poly__exact=geom)
|
---|
136 | Zipcode.objects.filter(poly=geom)
|
---|
137 | Zipcode.objects.filter(poly__same_as=geom)
|
---|
138 |
|
---|
139 | PostGIS equivalent::
|
---|
140 |
|
---|
141 | SELECT ... WHERE poly ~= geom
|
---|
142 |
|
---|
143 | :lookup:`left`
|
---|
144 | Tests if the geometry field's bounding box is strictly to the left of the
|
---|
145 | lookup geometry's bounding box.
|
---|
146 |
|
---|
147 | Example::
|
---|
148 |
|
---|
149 | Zipcode.objects.filter(poly__left=geom)
|
---|
150 |
|
---|
151 | PostGIS equivalent::
|
---|
152 |
|
---|
153 | SELECT ... WHERE poly << geom
|
---|
154 |
|
---|
155 | :lookup:`right`
|
---|
156 | Tests if the geometry field's bounding box is strictly to the right of the
|
---|
157 | lookup geometry's bounding box.
|
---|
158 |
|
---|
159 | Example::
|
---|
160 |
|
---|
161 | Zipcode.objects.filter(poly__right=geom)
|
---|
162 |
|
---|
163 | PostGIS equivalent::
|
---|
164 |
|
---|
165 | SELECT ... WHERE poly >> geom
|
---|
166 |
|
---|
167 | lookup:`overlaps_left`
|
---|
168 | Tests if the geometry field's bounding box overlaps or is to the left of the lookup
|
---|
169 | geometry's bounding box.
|
---|
170 |
|
---|
171 | Example::
|
---|
172 |
|
---|
173 | Zipcode.objects.filter(poly__overlaps_left=geom)
|
---|
174 |
|
---|
175 | PostGIS equivalent::
|
---|
176 |
|
---|
177 | SELECT ... WHERE poly &< geom
|
---|
178 |
|
---|
179 | :lookup:`overlaps_right`
|
---|
180 | Tests if the geometry field's bounding box overlaps or is to the right of the lookup
|
---|
181 | geometry's bounding box.
|
---|
182 |
|
---|
183 | Example::
|
---|
184 |
|
---|
185 | Zipcode.objects.filter(poly__overlaps_right=geom)
|
---|
186 |
|
---|
187 | PostGIS equivalent::
|
---|
188 |
|
---|
189 | SELECT ... WHERE poly &> geom
|
---|
190 |
|
---|
191 | :lookup:`overlaps_above`
|
---|
192 | Tests if the geometry field's bounding box overlaps or is above the lookup
|
---|
193 | geometry's bounding box.
|
---|
194 |
|
---|
195 | Example::
|
---|
196 |
|
---|
197 | Zipcode.objects.filter(poly__overlaps_above=geom)
|
---|
198 |
|
---|
199 | PostGIS equivalent::
|
---|
200 |
|
---|
201 | SELECT ... WHERE poly |&> geom
|
---|
202 |
|
---|
203 | :lookup:`overlaps_below`
|
---|
204 | Tests if the geometry field's bounding box overlaps or is below the lookup
|
---|
205 | geometry's bounding box.
|
---|
206 |
|
---|
207 | Example::
|
---|
208 |
|
---|
209 | Zipcode.objects.filter(poly__overlaps_below=geom)
|
---|
210 |
|
---|
211 | PostGIS equivalent::
|
---|
212 |
|
---|
213 | SELECT ... WHERE poly &<| geom
|
---|
214 |
|
---|
215 | :lookup:`strictly_above`
|
---|
216 | Tests if the geometry field's bounding box is strictly above the lookup
|
---|
217 | geometry's bounding box.
|
---|
218 |
|
---|
219 | Example::
|
---|
220 |
|
---|
221 | Zipcode.objects.filter(poly__strictly_above=geom)
|
---|
222 |
|
---|
223 | PostGIS equivalent::
|
---|
224 |
|
---|
225 | SELECT ... WHERE poly |>> geom
|
---|
226 |
|
---|
227 | :lookup:`strictly_below`
|
---|
228 | Tests if the geometry field's bounding box is strictly below the lookup
|
---|
229 | geometry's bounding box.
|
---|
230 |
|
---|
231 | Example::
|
---|
232 |
|
---|
233 | Zipcode.objects.filter(poly__strictly_below=geom)
|
---|
234 |
|
---|
235 | PostGIS equivalent::
|
---|
236 |
|
---|
237 | SELECT ... WHERE poly <<| geom
|
---|
238 |
|
---|
239 | Geometry Relationship Functions
|
---|
240 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
---|
241 |
|
---|
242 | The following lookup types correspond to PostGIS geometry relationship
|
---|
243 | functions. [#]_ Please note that when using PostGIS 1.3.1 and above, index
|
---|
244 | support is automatically "inlined" -- in other words, the bounding box
|
---|
245 | equivalent is automatically evaluated prior to calling these, more
|
---|
246 | computationally expensive, functions.
|
---|
247 |
|
---|
248 | :lookup:`contains`
|
---|
249 | Tests if the geometry field spatially contains the lookup geometry.
|
---|
250 |
|
---|
251 | Example::
|
---|
252 |
|
---|
253 | Zipcode.objects.filter(poly__contains=geom)
|
---|
254 |
|
---|
255 | PostGIS equivalent::
|
---|
256 |
|
---|
257 | SELECT ... WHERE ST_Contains(poly, geom)
|
---|
258 |
|
---|
259 | :lookup:`coveredby`
|
---|
260 | Tests if no point in the geometry field is outside the lookup geometry. [#]_
|
---|
261 | Only available in PostGIS 1.3.1 and above.
|
---|
262 |
|
---|
263 | Example::
|
---|
264 |
|
---|
265 | Zipcode.objects.filter(poly__coveredby=geom)
|
---|
266 |
|
---|
267 | PostGIS equivalent::
|
---|
268 |
|
---|
269 | SELECT ... WHERE ST_CoveredBy(poly, geom)
|
---|
270 |
|
---|
271 | :lookup:`covers`
|
---|
272 | Tests if no point in the lookup geometry is outside the geometry field. [#]_
|
---|
273 | Only available in PostGIS 1.3.1 and above.
|
---|
274 |
|
---|
275 | Example::
|
---|
276 |
|
---|
277 | Zipcode.objects.filter(poly__covers=geom)
|
---|
278 |
|
---|
279 | PostGIS equivalent::
|
---|
280 |
|
---|
281 | SELECT ... WHERE ST_Covers(poly, geom)
|
---|
282 |
|
---|
283 | :lookup:`crosses`
|
---|
284 | Tests if the geometry field spatially crosses the lookup geometry.
|
---|
285 |
|
---|
286 | Example::
|
---|
287 |
|
---|
288 | Zipcode.objects.filter(poly__crosses=geom)
|
---|
289 |
|
---|
290 | PostGIS equivalent::
|
---|
291 |
|
---|
292 | SELECT ... WHERE ST_Crosses(poly, geom)
|
---|
293 |
|
---|
294 | :lookup:`disjoint`
|
---|
295 | Tests if the geometry field is spatially disjoint from the lookup geometry.
|
---|
296 |
|
---|
297 | Example::
|
---|
298 |
|
---|
299 | Zipcode.objects.filter(poly__disjoint=geom)
|
---|
300 |
|
---|
301 | PostGIS equivalent::
|
---|
302 |
|
---|
303 | SELECT ... WHERE ST_Disjoint(poly, geom)
|
---|
304 |
|
---|
305 | .. _dwithin_postgis:
|
---|
306 |
|
---|
307 | :lookup:`dwithin`
|
---|
308 | Tests if the geometry field is within the specified distance of the lookup
|
---|
309 | geometry; uses indexes if available. The lookup parameter is a two-element
|
---|
310 | tuple: ``(geom, distance)``, where ``distance`` is a ``Distance`` object or a
|
---|
311 | numeric value in units. Only available in PostGIS versions 1.3.1 and above.
|
---|
312 |
|
---|
313 | .. admonition:: Distance Parameters and Geographic Coordinate Systems
|
---|
314 |
|
---|
315 | The ``dwithin`` lookup is meant for projected coordinate systems
|
---|
316 | because PostGIS uses ``ST_Distance``, which calculates the
|
---|
317 | Cartesian distance between geometries. In other words,
|
---|
318 | this will not return accurate results for geographic coordinate
|
---|
319 | systems such as WGS84. Thus, an exception will be raised if a
|
---|
320 | ``Distance`` object is used on a geometry field in a geographic
|
---|
321 | coordinate system.
|
---|
322 |
|
---|
323 | However, a numeric value is allowed for geometry fields in geographic
|
---|
324 | coordinate systems. This advanced usage allows users to limit
|
---|
325 | querysets by distance more efficiently using units of degrees.
|
---|
326 |
|
---|
327 | Example::
|
---|
328 |
|
---|
329 | # If Zipcode uses a projected coordinate system, this is allowed.
|
---|
330 | Zipcode.objects.filter(poly__dwithin=(geom, D(mi=5)))
|
---|
331 |
|
---|
332 | # If Zipcode uses a geographic coordinate system, then the
|
---|
333 | # distance unit must be a numeric value in units of degrees.
|
---|
334 | Zipcode.objects.filter(poly__dwithin=(geom, 0.5))
|
---|
335 |
|
---|
336 | PostGIS equivalent::
|
---|
337 |
|
---|
338 | SELECT ... WHERE ST_DWithin(poly, geom, <units value>)
|
---|
339 |
|
---|
340 | :lookup:`equals`
|
---|
341 | Tests if the geometry field is spatially equal to the lookup geometry.
|
---|
342 |
|
---|
343 | Example::
|
---|
344 |
|
---|
345 | Zipcode.objects.filter(poly__equals=geom)
|
---|
346 |
|
---|
347 | PostGIS equivalent::
|
---|
348 |
|
---|
349 | SELECT ... WHERE ST_Equals(poly, geom)
|
---|
350 |
|
---|
351 | :lookup:`intersects`
|
---|
352 | Tests if the geometry field spatially intersects the lookup geometry.
|
---|
353 |
|
---|
354 | Example::
|
---|
355 |
|
---|
356 | Zipcode.objects.filter(poly__intersects=geom)
|
---|
357 |
|
---|
358 | PostGIS equivalent::
|
---|
359 |
|
---|
360 | SELECT ... WHERE ST_Intersects(poly, geom)
|
---|
361 |
|
---|
362 | :lookup:`overlaps`
|
---|
363 | Tests if the geometry field spatially overlaps the lookup geometry.
|
---|
364 |
|
---|
365 | Example::
|
---|
366 |
|
---|
367 | Zipcode.objects.filter(poly__overlaps=geom)
|
---|
368 |
|
---|
369 | PostGIS equivalent::
|
---|
370 |
|
---|
371 | SELECT ... WHERE ST_Overlaps(poly, geom)
|
---|
372 |
|
---|
373 | :lookup:`relate`
|
---|
374 | Tests if the geometry field is spatially related to the the lookup geometry by
|
---|
375 | the values given in the intersection pattern matrix. The intersection pattern
|
---|
376 | matrix is a string comprising nine characters, which define intersections between
|
---|
377 | the interior, boundary, and exterior of the geometry field and the lookup geometry.
|
---|
378 | The intersection pattern matrix may only use the following characters:
|
---|
379 | ``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune"
|
---|
380 | a specific geometric relationship consistent with the DE-9IM model. [#]_
|
---|
381 |
|
---|
382 | Example::
|
---|
383 |
|
---|
384 | # A tuple lookup parameter is used to specify the geometry and
|
---|
385 | # the intersection pattern (the pattern here is for 'contains').
|
---|
386 | Zipcode.objects.filter(poly__relate(geom, 'T*T***FF*'))
|
---|
387 |
|
---|
388 | PostGIS equivalent::
|
---|
389 |
|
---|
390 | SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
|
---|
391 |
|
---|
392 | :lookup:`touches`
|
---|
393 | Tests if the geometry field spatially touches the lookup geometry.
|
---|
394 |
|
---|
395 | Example::
|
---|
396 |
|
---|
397 | Zipcode.objects.filter(poly__touches=geom)
|
---|
398 |
|
---|
399 | PostGIS equivalent::
|
---|
400 |
|
---|
401 | SELECT ... WHERE ST_Touches(poly, geom)
|
---|
402 |
|
---|
403 | :lookup:`within`
|
---|
404 | Tests if the geometry field is spatially within the lookup geometry.
|
---|
405 |
|
---|
406 | Example::
|
---|
407 |
|
---|
408 | Zipcode.objects.filter(poly__within=geom)
|
---|
409 |
|
---|
410 | PostGIS equivalent::
|
---|
411 |
|
---|
412 | SELECT ... WHERE ST_Within(poly, geom)
|
---|
413 |
|
---|
414 |
|
---|
415 | Oracle
|
---|
416 | ------
|
---|
417 | For more information, see Oracle's `Spatial Operators`__ documentation. [#]_
|
---|
418 |
|
---|
419 | __ http://download.oracle.com/docs/html/B14255_01/sdo_operat.htm
|
---|
420 |
|
---|
421 | :lookup:`contains`
|
---|
422 | Tests if the geometry field spatially contains the lookup geometry.
|
---|
423 |
|
---|
424 | Example::
|
---|
425 |
|
---|
426 | Zipcode.objects.filter(poly__contains=geom)
|
---|
427 |
|
---|
428 | Oracle equivalent::
|
---|
429 |
|
---|
430 | SELECT ... WHERE SDO_CONTAINS(poly, geom)
|
---|
431 |
|
---|
432 | :lookup:`covers`
|
---|
433 | Tests if no point in the lookup geometry is outside the geometry field.
|
---|
434 |
|
---|
435 | Oracle equivalent::
|
---|
436 |
|
---|
437 | SELECT ... WHERE SDO_COVERS(poly, geom)
|
---|
438 |
|
---|
439 | :lookup:`coveredby`
|
---|
440 | Tests if no point in the geometry field is outside the lookup geometry.
|
---|
441 |
|
---|
442 | Oracle equivalent::
|
---|
443 |
|
---|
444 | SELECT ... WHERE SDO_COVEREDBY(poly, geom)
|
---|
445 |
|
---|
446 | :lookup:`disjoint`
|
---|
447 | Tests if the geometry field is spatially disjoint from the lookup geometry.
|
---|
448 |
|
---|
449 | Oracle equivalent::
|
---|
450 |
|
---|
451 | SELECT ... WHERE SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)
|
---|
452 |
|
---|
453 | :lookup:`dwithin`
|
---|
454 | Tests if the geometry field is within the specified distance of the lookup
|
---|
455 | geometry; uses indexes if available. The lookup parameter is a two-element
|
---|
456 | tuple: ``(geom, distance)``, where ``distance`` is a ``Distance`` object or a
|
---|
457 | numeric value in units.
|
---|
458 |
|
---|
459 | Oracle equivalent::
|
---|
460 |
|
---|
461 | SELECT ... WHERE SDO_WITHIN_DISTANCE(poly, geom, 'distance=distance')
|
---|
462 |
|
---|
463 | :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
|
---|
464 | Tests if the geometry field is spatially equal to the lookup geometry.
|
---|
465 | The following examples are equivalent on Oracle::
|
---|
466 |
|
---|
467 | Zipcode.objects.filter(poly=geom)
|
---|
468 | Zipcode.objects.filter(poly__exact=geom)
|
---|
469 | Zipcode.objects.filter(poly__equals=geom)
|
---|
470 | Zipcode.objects.filter(poly__same_as=geom)
|
---|
471 |
|
---|
472 | Oracle equivalent::
|
---|
473 |
|
---|
474 | SELECT ... WHERE SDO_EQUALS(poly, geom)
|
---|
475 |
|
---|
476 | :lookup:`intersects`
|
---|
477 | Tests if the geometry field spatially intersects the lookup geometry.
|
---|
478 |
|
---|
479 | Oracle equivalent::
|
---|
480 |
|
---|
481 | SELECT ... WHERE SDO_OVERLAPBDYINTERSECT(poly, geom)
|
---|
482 |
|
---|
483 | :lookup:`overlaps`
|
---|
484 | Tests if the geometry field spatially overlaps the lookup geometry.
|
---|
485 |
|
---|
486 | Oracle equivalent::
|
---|
487 |
|
---|
488 | SELECT ... WHERE SDO_OVERLAPS(poly, geom)
|
---|
489 |
|
---|
490 | :lookup:`relate`
|
---|
491 | Tests if the geometry field is spatially related to the the lookup geometry by
|
---|
492 | the given mask component. This lookup requires a tuple parameter,
|
---|
493 | ``(geom, mask)``, where ``mask`` is at least one of the nine-intersection
|
---|
494 | patterns: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
|
---|
495 | ``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ANYINTERACT``,
|
---|
496 | and ``ON``. Multiple masks may be combined with the logical Boolean operator
|
---|
497 | OR, for example, ``'inside+touch'``. [#]_ The mask relation strings are
|
---|
498 | case-insensitive.
|
---|
499 |
|
---|
500 | Example::
|
---|
501 |
|
---|
502 | # A tuple lookup parameter is used to specify the geometry and
|
---|
503 | # the mask component.
|
---|
504 | Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
|
---|
505 |
|
---|
506 | Oracle equivalent::
|
---|
507 |
|
---|
508 | SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
|
---|
509 |
|
---|
510 | :lookup:`touches`
|
---|
511 | Tests if the geometry field spatially touches the lookup geometry.
|
---|
512 |
|
---|
513 | Oracle equivalent::
|
---|
514 |
|
---|
515 | SELECT ... WHERE SDO_TOUCH(poly, geom)
|
---|
516 |
|
---|
517 | :lookup:`within`
|
---|
518 | Tests if the geometry field is spatially within (inside) the lookup
|
---|
519 | geometry.
|
---|
520 |
|
---|
521 | Oracle equivalent::
|
---|
522 |
|
---|
523 | SELECT ... WHERE SDO_INSIDE(poly, geom)
|
---|
524 |
|
---|
525 | MySQL
|
---|
526 | -----
|
---|
527 | For more information, see `Relations on Geometry Minimal Bounding Rectangles (MBRs)`__. [#]_
|
---|
528 |
|
---|
529 | __ http://dev.mysql.com/doc/refman/5.0/en/relations-on-geometry-mbr.html
|
---|
530 |
|
---|
531 | :lookup:`bbcontains`, :lookup:`contains`
|
---|
532 | * MySQL equivalent ``MBRContains(g1, g2)``
|
---|
533 |
|
---|
534 | :lookup:`contained`, :lookup:`within`
|
---|
535 | * MySQL equivalent ``MBRWithin(g1, g2)``
|
---|
536 |
|
---|
537 | :lookup:`disjoint`
|
---|
538 | * MySQL equivalent ``MBRDisjoint(g1, g2)``
|
---|
539 |
|
---|
540 | :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
|
---|
541 | * MySQL equivalent ``MBREqual(g1, g2)``
|
---|
542 |
|
---|
543 | :lookup:`intersects`
|
---|
544 | * MySQL equivalent ``MBRIntersects(g1, g2)``
|
---|
545 |
|
---|
546 | :lookup:`overlaps`
|
---|
547 | * MySQL equivalent ``MBROverlaps(g1, g2)``
|
---|
548 |
|
---|
549 | :lookup:`touches`
|
---|
550 | * MySQL equivalent ``MBRTouches(g1, g2)``
|
---|
551 |
|
---|
552 | SpatiaLite
|
---|
553 | ----------
|
---|
554 |
|
---|
555 | For more information consult the `SpatiaLite SQL functions reference list`__.
|
---|
556 |
|
---|
557 | __ http://www.gaia-gis.it/spatialite/spatialite-sql-2.3.1.html
|
---|
558 |
|
---|
559 | :lookup:`bbcontains`
|
---|
560 | * SpatiaLite equivalient ``MbrContains(g1, g2)``
|
---|
561 |
|
---|
562 | :lookup:`bboverlaps`
|
---|
563 | * SpatiaLite equivalent ``MbrOverlaps(g1, g2)``
|
---|
564 |
|
---|
565 | :lookup:`contained`
|
---|
566 | * SpatiaLite equivalent ``MbrWithin(g1, g2)``
|
---|
567 |
|
---|
568 | :lookup:`contains`
|
---|
569 | * SpatiaLite equivalent ``Contains(g1, g2)``
|
---|
570 |
|
---|
571 | :lookup:`crosses`
|
---|
572 | * SpatiaLite equivalent ``Crosses(g1, g2)``
|
---|
573 |
|
---|
574 | :lookup:`disjoint`
|
---|
575 | * SpatiaLite equivalent ``Disjoint(g1, g2)``
|
---|
576 |
|
---|
577 | :lookup:`equals`, :lookup:`exact`, :lookup:`same_as`
|
---|
578 | * SpatiaLite equivalent ``Equals(g1, g2)``
|
---|
579 |
|
---|
580 | :lookup:`intersects`
|
---|
581 | * SpatiaLite equivalent ``Intersects(g1, g2)``
|
---|
582 |
|
---|
583 | :lookup:`overlaps`
|
---|
584 | * SpatiaLite equivalent ``Overlaps(g1, g2)``
|
---|
585 |
|
---|
586 | :lookup:`relate`
|
---|
587 | * SpatiaLite equivalent ``Relate(geom, pattern)``
|
---|
588 |
|
---|
589 | :lookup:`touches`
|
---|
590 | * SpatiaLite equivalent ``Touches(g1, g2)``
|
---|
591 |
|
---|
592 | :lookup:`within`
|
---|
593 | * SpatiaLite equivalent ``Within(g1, g2)``
|
---|
594 |
|
---|
595 |
|
---|
596 | Distance Queries
|
---|
597 | ================
|
---|
598 |
|
---|
599 | Introduction
|
---|
600 | ------------
|
---|
601 | Distance calculations with spatial data is tricky because, unfortunately,
|
---|
602 | the Earth is not flat. Some distance queries with fields in a geographic
|
---|
603 | coordinate system may have to be expressed differently because of
|
---|
604 | limitations in PostGIS. Please see the `Selecting an SRID`_ section in the
|
---|
605 | model API documentation for more details.
|
---|
606 |
|
---|
607 | .. _Selecting an SRID: model-api.html#selecting-an-srid
|
---|
608 |
|
---|
609 | Distance Lookups
|
---|
610 | ----------------
|
---|
611 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
612 |
|
---|
613 | Distance lookups take a tuple parameter comprising:
|
---|
614 |
|
---|
615 | #. A geometry to base calculations from; and
|
---|
616 | #. A number or ``Distance`` object containing the distance.
|
---|
617 |
|
---|
618 | If a ``Distance`` [#]_ object is used, it may be expressed in
|
---|
619 | any units (the SQL generated will use units converted to those of the field);
|
---|
620 | otherwise, numeric parameters will be assumed to be in the units of the field.
|
---|
621 |
|
---|
622 | .. note::
|
---|
623 |
|
---|
624 | For PostGIS users, the routine ``ST_distance_sphere``
|
---|
625 | is used by default for calculating distances on geographic coordinate systems
|
---|
626 | -- which may only be called with point geometries [#]_. Thus,
|
---|
627 | geographic distance lookups on PostGIS are only allowed on ``PointField``
|
---|
628 | model fields using points for the geographic parameter.
|
---|
629 |
|
---|
630 | The following distance lookups are available:
|
---|
631 |
|
---|
632 | * :lookup:`distance_lt`
|
---|
633 | * :lookup:`distance_lte`
|
---|
634 | * :lookup:`distance_gt`
|
---|
635 | * :lookup:`distance_gte`
|
---|
636 | * :lookup:`dwithin`
|
---|
637 |
|
---|
638 | In addition, there's the :ref:`distance` ``GeoQuerySet`` method.
|
---|
639 |
|
---|
640 | For example, let's say we have a ``SouthTexasCity`` model (from the
|
---|
641 | `GeoDjango distance tests`__ ) on a *projected* coordinate system valid for cities
|
---|
642 | in southern Texas::
|
---|
643 |
|
---|
644 | from django.contrib.gis.db import models
|
---|
645 |
|
---|
646 | class SouthTexasCity(models.Model):
|
---|
647 | name = models.CharField(max_length=30)
|
---|
648 | # A projected coordinate system (only valid for South Texas!)
|
---|
649 | # is used, units are in meters.
|
---|
650 | point = models.PointField(srid=32140)
|
---|
651 | objects = models.GeoManager()
|
---|
652 |
|
---|
653 | Then distance queries may be performed as follows::
|
---|
654 |
|
---|
655 | >>> from django.contrib.gis.geos import *
|
---|
656 | >>> from django.contrib.gis.measure import D # ``D`` is a shortcut for ``Distance``
|
---|
657 | >>> from geoapp import SouthTexasCity
|
---|
658 | # Distances will be calculated from this point, which does not have to be projected.
|
---|
659 | >>> pnt = fromstr('POINT(-96.876369 29.905320)', srid=4326)
|
---|
660 | # If numeric parameter, units of field (meters in this case) are assumed.
|
---|
661 | >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, 7000))
|
---|
662 | # Find all Cities within 7 km, > 20 miles away, and > 100 chains away (an obscure unit)
|
---|
663 | >>> qs = SouthTexasCity.objects.filter(point__distance_lte=(pnt, D(km=7)))
|
---|
664 | >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(mi=20)))
|
---|
665 | >>> qs = SouthTexasCity.objects.filter(point__distance_gte=(pnt, D(chain=100)))
|
---|
666 |
|
---|
667 | __ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
|
---|
668 |
|
---|
669 | .. _geoqs_methods:
|
---|
670 |
|
---|
671 | ``GeoQuerySet`` Methods
|
---|
672 | =======================
|
---|
673 |
|
---|
674 | ``GeoQuerySet`` methods perform a spatial operation on each geographic
|
---|
675 | field in the queryset and store its output in a new attribute on the model
|
---|
676 | (which is generally the name of the ``GeoQuerySet`` method).
|
---|
677 |
|
---|
678 | There are also aggregate ``GeoQuerySet`` methods which return a single value
|
---|
679 | instead of a queryset. This section will describe the API and availability
|
---|
680 | of every ``GeoQuerySet`` method available in GeoDjango.
|
---|
681 |
|
---|
682 | With a few exceptions, the following keyword arguments may be used with all
|
---|
683 | ``GeoQuerySet`` methods:
|
---|
684 |
|
---|
685 | ===================== =====================================================
|
---|
686 | Keyword Argument Description
|
---|
687 | ===================== =====================================================
|
---|
688 | ``field_name`` By default, ``GeoQuerySet`` methods use the first
|
---|
689 | geographic field encountered in the model. This
|
---|
690 | keyword should be used to specify another
|
---|
691 | geographic field (e.g., ``field_name='point2'``)
|
---|
692 | when there are multiple geographic fields in a model.
|
---|
693 |
|
---|
694 | On PostGIS, the ``field_name`` keyword may also be
|
---|
695 | used on geometry fields in models that are related
|
---|
696 | via a ``ForeignKey`` relation (e.g.,
|
---|
697 | ``field_name='related__point'``).
|
---|
698 |
|
---|
699 | ``model_att`` By default, ``GeoQuerySet`` methods typically attach
|
---|
700 | their output in an attribute with the same name as
|
---|
701 | the ``GeoQuerySet`` method. Setting this keyword
|
---|
702 | with the desired attribute name will override this
|
---|
703 | default behavior. For example,
|
---|
704 | ``qs = Zipcode.objects.centroid(model_att='c')`` will
|
---|
705 | attach the centroid of the ``Zipcode`` geometry field
|
---|
706 | in a ``c`` attribute on every model rather than in a
|
---|
707 | ``centroid`` attribute.
|
---|
708 |
|
---|
709 | This keyword is required if
|
---|
710 | a method name clashes with an existing
|
---|
711 | ``GeoQuerySet`` method -- if you wanted to use the
|
---|
712 | ``area()`` method on model with a ``PolygonField``
|
---|
713 | named ``area``, for example.
|
---|
714 | ===================== =====================================================
|
---|
715 |
|
---|
716 | Aggregate Objects
|
---|
717 | -----------------
|
---|
718 | .. versionadded:: 1.1
|
---|
719 |
|
---|
720 | Example::
|
---|
721 |
|
---|
722 | >>> from django.contrib.gis.db.models import Extent, Union
|
---|
723 | >>> WorldBorders.objects.aggregate(Extent('mpoly'), Union('mpoly'))
|
---|
724 |
|
---|
725 | .. method:: Collect
|
---|
726 |
|
---|
727 | Returns the same as the :ref:`collect` aggregate method.
|
---|
728 |
|
---|
729 | .. method:: Extent
|
---|
730 |
|
---|
731 | Returns the same as the :ref:`extent` aggregate method.
|
---|
732 |
|
---|
733 | .. method:: Extent3D
|
---|
734 |
|
---|
735 | .. versionadded:: 1.2
|
---|
736 |
|
---|
737 | Returns the same as the :ref:`extent3d` aggregate method.
|
---|
738 |
|
---|
739 | .. method:: MakeLine
|
---|
740 |
|
---|
741 | Returns the same as the :ref:`makeline` aggregate method.
|
---|
742 |
|
---|
743 | .. method:: Union
|
---|
744 |
|
---|
745 | Returns the same as the :ref:`unionagg` aggregate method.
|
---|
746 |
|
---|
747 | Aggregate Methods
|
---|
748 | -----------------
|
---|
749 |
|
---|
750 | .. _collect:
|
---|
751 |
|
---|
752 | .. method:: collect()
|
---|
753 |
|
---|
754 | .. versionadded:: 1.1
|
---|
755 |
|
---|
756 | *Availability*: PostGIS
|
---|
757 |
|
---|
758 | Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
|
---|
759 | column. This is analagous to a simplified version of the :ref:`unionagg` routine,
|
---|
760 | except it can be several orders of magnitude faster than peforming a union because
|
---|
761 | it simply rolls up geometries into a collection or multi object, not caring about
|
---|
762 | dissolving boundaries.
|
---|
763 |
|
---|
764 | .. _extent:
|
---|
765 |
|
---|
766 | .. method:: extent()
|
---|
767 |
|
---|
768 | *Availability*: PostGIS, Oracle
|
---|
769 |
|
---|
770 | Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the
|
---|
771 | lower left coordinate and the upper right coordinate.
|
---|
772 |
|
---|
773 | Example::
|
---|
774 |
|
---|
775 | >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
|
---|
776 | >>> print qs.extent()
|
---|
777 | (-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
|
---|
778 |
|
---|
779 |
|
---|
780 | .. _extent3d:
|
---|
781 |
|
---|
782 | .. method:: extent3d()
|
---|
783 |
|
---|
784 | .. versionadded:: 1.2
|
---|
785 |
|
---|
786 | *Availability*: PostGIS
|
---|
787 |
|
---|
788 | Returns the 3D extent of the ``GeoQuerySet`` as a six-tuple, comprising
|
---|
789 | the lower left coordinate and upper right coordinate.
|
---|
790 |
|
---|
791 | Example::
|
---|
792 |
|
---|
793 | >>> qs = City.objects.filter(name__in=('Houston', 'Dallas'))
|
---|
794 | >>> print qs.extent3d()
|
---|
795 | (-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
|
---|
796 |
|
---|
797 | .. _makeline:
|
---|
798 |
|
---|
799 | .. method:: make_line()
|
---|
800 |
|
---|
801 | *Availability*: PostGIS
|
---|
802 |
|
---|
803 | Returns a ``LineString`` constructed from the point field geometries in the
|
---|
804 | ``GeoQuerySet``. Currently, ordering the queryset has no effect.
|
---|
805 |
|
---|
806 | Example::
|
---|
807 |
|
---|
808 | >>> print City.objects.filter(name__in=('Houston', 'Dallas')).make_line()
|
---|
809 | LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
|
---|
810 |
|
---|
811 | .. _unionagg:
|
---|
812 |
|
---|
813 | .. function:: unionagg()
|
---|
814 |
|
---|
815 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
816 |
|
---|
817 | This method returns a ``GEOSGeometry`` object comprising the union of every
|
---|
818 | geometry in the queryset. Please note that use of `unionagg` is processor intensive
|
---|
819 | and may take a significant amount of time on large querysets.
|
---|
820 |
|
---|
821 | Example::
|
---|
822 |
|
---|
823 | >>> u = Zipcode.objects.unionagg() # This may take a long time.
|
---|
824 | >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach.
|
---|
825 |
|
---|
826 | ===================== =====================================================
|
---|
827 | Keyword Argument Description
|
---|
828 | ===================== =====================================================
|
---|
829 | ``tolerance`` This keyword is for Oracle only. It is for the
|
---|
830 | tolerance value used by the ``SDOAGGRTYPE``
|
---|
831 | procedure; the `Oracle documentation`__ has more
|
---|
832 | details.
|
---|
833 | ===================== =====================================================
|
---|
834 |
|
---|
835 | __ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
|
---|
836 |
|
---|
837 | Measurement
|
---|
838 | -----------
|
---|
839 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
840 |
|
---|
841 | .. _area:
|
---|
842 |
|
---|
843 | .. function:: area()
|
---|
844 |
|
---|
845 | Returns the area of the geographic field in an ``area`` attribute on
|
---|
846 | each element of this GeoQuerySet.
|
---|
847 |
|
---|
848 | .. _distance:
|
---|
849 |
|
---|
850 | .. function:: distance(geom)
|
---|
851 |
|
---|
852 | This method takes a geometry as a parameter, and attaches a ``distance``
|
---|
853 | attribute to every model in the returned queryset that contains the
|
---|
854 | distance (as a ``Distance`` object) to the given geometry.
|
---|
855 |
|
---|
856 | In the following example (taken from the `GeoDjango distance tests`__),
|
---|
857 | the distance from the `Tasmanian`__ city of Hobart to every other
|
---|
858 | ``PointField`` in the ``AustraliaCity`` queryset is calculated::
|
---|
859 |
|
---|
860 | >>> pnt = AustraliaCity.objects.get(name='Hobart').point
|
---|
861 | >>> for city in AustraliaCity.objects.distance(pnt): print city.name, city.distance
|
---|
862 | Wollongong 990071.220408 m
|
---|
863 | Shellharbour 972804.613941 m
|
---|
864 | Thirroul 1002334.36351 m
|
---|
865 | Mittagong 975691.632637 m
|
---|
866 | Batemans Bay 834342.185561 m
|
---|
867 | Canberra 598140.268959 m
|
---|
868 | Melbourne 575337.765042 m
|
---|
869 | Sydney 1056978.87363 m
|
---|
870 | Hobart 0.0 m
|
---|
871 | Adelaide 1162031.83522 m
|
---|
872 | Hillsdale 1049200.46122 m
|
---|
873 |
|
---|
874 | .. note::
|
---|
875 |
|
---|
876 | Because the ``distance`` attribute is a ``Distance`` object, you can
|
---|
877 | easily express the value in the units of your choice. For example,
|
---|
878 | ``city.distance.mi`` is the distance value in miles and
|
---|
879 | ``city.distance.km`` is the distance value in kilometers. See the
|
---|
880 | `distance documentation`_ for usage details and the list of
|
---|
881 | `supported units`_.
|
---|
882 |
|
---|
883 | .. _distance documentation: measure.html#the-distance-and-area-objects
|
---|
884 | .. _supported units: measure.html#supported-units
|
---|
885 |
|
---|
886 | __ http://en.wikipedia.org/wiki/Tasmania
|
---|
887 | __ http://code.djangoproject.com/browser/django/trunk/django/contrib/gis/tests/distapp/models.py
|
---|
888 |
|
---|
889 | .. function:: length()
|
---|
890 |
|
---|
891 | Returns the length of the geometry field in a ``length`` attribute
|
---|
892 | (a ``Distance`` object) on each model in the queryset.
|
---|
893 |
|
---|
894 | .. function:: perimiter()
|
---|
895 |
|
---|
896 | Returns the perimeter of the geometry field in a ``perimeter`` attribute
|
---|
897 | (a ``Distance`` object) on each model in the queryset.
|
---|
898 |
|
---|
899 | Geometry Methods
|
---|
900 | ----------------
|
---|
901 |
|
---|
902 | With the exception of ``transform``, all of the following attach geometry objects
|
---|
903 | to each element of the ``GeoQuerySet`` that is the result of the method.
|
---|
904 |
|
---|
905 | .. function:: centroid()
|
---|
906 |
|
---|
907 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
908 |
|
---|
909 | Returns the ``centroid`` value for the geographic field in a ``centroid``
|
---|
910 | attribute on each element of the ``GeoQuerySet``.
|
---|
911 |
|
---|
912 | .. function:: envelope()
|
---|
913 |
|
---|
914 | *Availability*: PostGIS, SpatiaLite
|
---|
915 |
|
---|
916 | Returns a geometry representing the bounding box of the geometry field in
|
---|
917 | an ``envelope`` attribute on each element of the ``GeoQuerySet``.
|
---|
918 |
|
---|
919 | .. function: point_on_surface()
|
---|
920 |
|
---|
921 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
922 |
|
---|
923 | Returns a Point geometry guaranteed to lie on the surface of the
|
---|
924 | Geometry field in a `point_on_surface` attribute on each element
|
---|
925 | of this GeoQuerySet; otherwise sets with None.
|
---|
926 |
|
---|
927 | .. function:: scale(x, y, z=0.0)
|
---|
928 |
|
---|
929 | *Availability*: PostGIS, SpatiaLite
|
---|
930 |
|
---|
931 | .. function:: snap_to_grid(*args)
|
---|
932 |
|
---|
933 | .. versionadded:: 1.1
|
---|
934 |
|
---|
935 | Snap all points of the input geometry to the grid. How the
|
---|
936 | geometry is snapped to the grid depends on how many numeric
|
---|
937 | (either float, integer, or long) arguments are given.
|
---|
938 |
|
---|
939 | =================== =====================================================
|
---|
940 | Number of Arguments Description
|
---|
941 | =================== =====================================================
|
---|
942 | 1 A single size to snap bot the X and Y grids to.
|
---|
943 | 2 X and Y sizes to snap the grid to.
|
---|
944 | 4 X, Y sizes and the corresponding X, Y origins.
|
---|
945 | =================== =====================================================
|
---|
946 |
|
---|
947 | .. function:: translate(x, y, z=0.0)
|
---|
948 |
|
---|
949 | *Availability*: PostGIS, SpatiaLite
|
---|
950 |
|
---|
951 | Translates the geometry to a new location using the given numeric
|
---|
952 | parameters as offsets.
|
---|
953 |
|
---|
954 | .. function:: transform(srid)
|
---|
955 |
|
---|
956 | *Availability*: PostGIS, Oracle
|
---|
957 |
|
---|
958 | The ``transform`` method transforms the geometries in a model to the spatial
|
---|
959 | reference system specified by the ``srid`` parameter. If no ``srid`` is given,
|
---|
960 | then 4326 (WGS84) is used by default.
|
---|
961 |
|
---|
962 | .. note ::
|
---|
963 |
|
---|
964 | What spatial reference system an integer SRID corresponds to may depend on
|
---|
965 | the spatial database used. In other words, the SRID numbers used for Oracle
|
---|
966 | are not necessarily the same as those used by PostGIS.
|
---|
967 |
|
---|
968 | Example::
|
---|
969 |
|
---|
970 | >>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
|
---|
971 | >>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
|
---|
972 | >>> print qs[0].poly.srid
|
---|
973 | 32140
|
---|
974 | >>> print qs[0].poly
|
---|
975 | POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
|
---|
976 |
|
---|
977 | Geometry Operations
|
---|
978 | -------------------
|
---|
979 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
980 |
|
---|
981 | The following methods all take a geometry as a parameter and attach a geometry
|
---|
982 | to each element of the ``GeoQuerySet`` that is the result of the operation.
|
---|
983 |
|
---|
984 | .. function:: difference(geom)
|
---|
985 |
|
---|
986 | Returns the spatial difference of the geographic field with the given
|
---|
987 | geometry in a ``difference`` attribute on each element of the
|
---|
988 | ``GeoQuerySet``.
|
---|
989 |
|
---|
990 | .. function:: intersection(geom)
|
---|
991 |
|
---|
992 | Returns the spatial intersection of the geographic field with the
|
---|
993 | given geometry in an ``intersection`` attribute on each element of the
|
---|
994 | ``GeoQuerySet``.
|
---|
995 |
|
---|
996 | .. function:: sym_difference(geom)
|
---|
997 |
|
---|
998 | Returns the symmetric difference of the geographic field with the
|
---|
999 | given geometry in a ``sym_difference`` attribute on each element of the
|
---|
1000 | ``GeoQuerySet``.
|
---|
1001 |
|
---|
1002 | .. function:: union(geom)
|
---|
1003 |
|
---|
1004 | Returns the union of the geographic field with the given
|
---|
1005 | geometry in an ``union`` attribute on each element of the
|
---|
1006 | ``GeoQuerySet``.
|
---|
1007 |
|
---|
1008 | Output
|
---|
1009 | ------
|
---|
1010 |
|
---|
1011 | The following ``GeoQuerySet`` methods will return an attribute that has the value
|
---|
1012 | of the geometry field in each model converted to the requested output format.
|
---|
1013 |
|
---|
1014 | .. function:: geojson()
|
---|
1015 |
|
---|
1016 | .. versionadded:: 1.1
|
---|
1017 |
|
---|
1018 | *Availability*: PostGIS
|
---|
1019 |
|
---|
1020 | Attaches a ``geojson`` attribute to every model in the queryset that contains the
|
---|
1021 | `GeoJSON`__ representation of the geometry.
|
---|
1022 |
|
---|
1023 | ===================== =====================================================
|
---|
1024 | Keyword Argument Description
|
---|
1025 | ===================== =====================================================
|
---|
1026 | ``precision`` It may be used to specify the number of significant
|
---|
1027 | digits for the coordinates in the GeoJSON
|
---|
1028 | representation -- the default value is 8.
|
---|
1029 |
|
---|
1030 | ``crs`` Set this to ``True`` if you want the coordinate
|
---|
1031 | reference system to be included in the returned
|
---|
1032 | GeoJSON.
|
---|
1033 |
|
---|
1034 | ``bbox`` Set this to ``True`` if you want the bounding box
|
---|
1035 | to be included in the returned GeoJSON.
|
---|
1036 | ===================== =====================================================
|
---|
1037 |
|
---|
1038 | __ http://geojson.org/
|
---|
1039 |
|
---|
1040 | .. function:: gml()
|
---|
1041 |
|
---|
1042 | *Availability*: PostGIS, Oracle
|
---|
1043 |
|
---|
1044 | Attaches a ``gml`` attribute to every model in the queryset that contains the
|
---|
1045 | `Geographic Markup Language (GML)`__ representation of the geometry.
|
---|
1046 |
|
---|
1047 | Example::
|
---|
1048 |
|
---|
1049 | >>> qs = Zipcode.objects.all().gml()
|
---|
1050 | >>> print qs[0].gml
|
---|
1051 | <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
|
---|
1052 |
|
---|
1053 | ===================== =====================================================
|
---|
1054 | Keyword Argument Description
|
---|
1055 | ===================== =====================================================
|
---|
1056 | ``precision`` This keyword is for PostGIS only. It may be used
|
---|
1057 | to specify the number of significant digits for the
|
---|
1058 | coordinates in the GML representation -- the default
|
---|
1059 | value is 8.
|
---|
1060 |
|
---|
1061 | ``version`` This keyword is for PostGIS only. It may be used to
|
---|
1062 | specify the GML version used, and may only be values
|
---|
1063 | of 2 or 3. The default value is 2.
|
---|
1064 | ===================== =====================================================
|
---|
1065 |
|
---|
1066 | __ http://en.wikipedia.org/wiki/Geography_Markup_Language
|
---|
1067 |
|
---|
1068 | .. function:: kml()
|
---|
1069 |
|
---|
1070 | *Availability*: PostGIS
|
---|
1071 |
|
---|
1072 | Attaches a ``kml`` attribute to every model in the queryset that contains the
|
---|
1073 | `Keyhole Markup Language (KML)`__ representation of the geometry fields. It
|
---|
1074 | should be noted that the contents of the KML are transformed to WGS84 if
|
---|
1075 | necessary.
|
---|
1076 |
|
---|
1077 | Example::
|
---|
1078 |
|
---|
1079 | >>> qs = Zipcode.objects.all().kml()
|
---|
1080 | >>> print qs[0].kml
|
---|
1081 | <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
|
---|
1082 |
|
---|
1083 | ===================== =====================================================
|
---|
1084 | Keyword Argument Description
|
---|
1085 | ===================== =====================================================
|
---|
1086 | ``precision`` This keyword may be used to specify the number of
|
---|
1087 | significant digits for the coordinates in the KML
|
---|
1088 | representation -- the default value is 8.
|
---|
1089 | ===================== =====================================================
|
---|
1090 |
|
---|
1091 | __ http://code.google.com/apis/kml/documentation/
|
---|
1092 |
|
---|
1093 | .. function:: svg()
|
---|
1094 |
|
---|
1095 | *Availability*: PostGIS, SpatiaLite
|
---|
1096 |
|
---|
1097 | Attaches a ``svg`` attribute to every model in the queryset that contains
|
---|
1098 | the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields.
|
---|
1099 |
|
---|
1100 | ===================== =====================================================
|
---|
1101 | Keyword Argument Description
|
---|
1102 | ===================== =====================================================
|
---|
1103 | ``relative`` If set to ``True``, the path data will be implemented
|
---|
1104 | in terms of relative moves. Defaults to ``False``,
|
---|
1105 | meaning that absolute moves are used instead.
|
---|
1106 |
|
---|
1107 | ``precision`` This keyword may be used to specify the number of
|
---|
1108 | significant digits for the coordinates in the SVG
|
---|
1109 | representation -- the default value is 8.
|
---|
1110 | ===================== =====================================================
|
---|
1111 |
|
---|
1112 | __ http://www.w3.org/Graphics/SVG/
|
---|
1113 |
|
---|
1114 | Miscellaneous
|
---|
1115 | -------------
|
---|
1116 |
|
---|
1117 | .. function:: mem_size()
|
---|
1118 |
|
---|
1119 | *Availability*: PostGIS
|
---|
1120 |
|
---|
1121 | Returns the memory size (number of bytes) that the geometry field takes
|
---|
1122 | in a ``mem_size`` attribute on each element of the ``GeoQuerySet``.
|
---|
1123 |
|
---|
1124 | .. function:: num_geom()
|
---|
1125 |
|
---|
1126 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
1127 |
|
---|
1128 | Returns the number of geometries in a ``num_geom`` attribute on
|
---|
1129 | each element of the ``GeoQuerySet`` if the geometry field is a
|
---|
1130 | collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field);
|
---|
1131 | otherwise sets with ``None``.
|
---|
1132 |
|
---|
1133 | .. function:: num_points()
|
---|
1134 |
|
---|
1135 | *Availability*: PostGIS, Oracle, SpatiaLite
|
---|
1136 |
|
---|
1137 | Returns the number of points in the first linestring in the
|
---|
1138 | geometry field in a ``num_points`` attribute on each element of
|
---|
1139 | the ``GeoQuerySet``; otherwise sets with ``None``.
|
---|
1140 |
|
---|
1141 | Compatibility Table
|
---|
1142 | ===================
|
---|
1143 |
|
---|
1144 | Spatial Lookup Types
|
---|
1145 | --------------------
|
---|
1146 | The following table provides a summary of what lookup types are available
|
---|
1147 | on each spatial backend.
|
---|
1148 |
|
---|
1149 | =========================== ========= ======== ============ ==========
|
---|
1150 | Lookup Type PostGIS Oracle MySQL [#]_ SpatiaLite
|
---|
1151 | =========================== ========= ======== ============ ==========
|
---|
1152 | ``bbcontains`` X X X
|
---|
1153 | ``bboverlaps`` X X X
|
---|
1154 | ``contained`` X X X
|
---|
1155 | ``contains`` X X X X
|
---|
1156 | ``coveredby`` X X
|
---|
1157 | ``covers`` X X
|
---|
1158 | ``crosses`` X X
|
---|
1159 | ``disjoint`` X X X X
|
---|
1160 | ``distance_gt`` X X X
|
---|
1161 | ``distance_gte`` X X X
|
---|
1162 | ``distance_lt`` X X X
|
---|
1163 | ``distance_lte`` X X X
|
---|
1164 | ``dwithin`` X X
|
---|
1165 | ``equals`` X X X X
|
---|
1166 | ``exact`` X X X X
|
---|
1167 | ``intersects`` X X X X
|
---|
1168 | ``overlaps`` X X X X
|
---|
1169 | ``relate`` X X X
|
---|
1170 | ``same_as`` X X X X
|
---|
1171 | ``touches`` X X X X
|
---|
1172 | ``within`` X X X X
|
---|
1173 | ``left`` X
|
---|
1174 | ``right`` X
|
---|
1175 | ``overlaps_left`` X
|
---|
1176 | ``overlaps_right`` X
|
---|
1177 | ``overlaps_above`` X
|
---|
1178 | ``overlaps_below`` X
|
---|
1179 | ``strictly_above`` X
|
---|
1180 | ``strictly_below`` X
|
---|
1181 | =========================== ========= ======== ============ ==========
|
---|
1182 |
|
---|
1183 | ``GeoQuerySet`` Methods
|
---|
1184 | -----------------------
|
---|
1185 | The following table provides a summary of what ``GeoQuerySet`` methods
|
---|
1186 | are available on each spatial backend. Please note that MySQL does not
|
---|
1187 | support any of these methods, and is thus excluded from the table.
|
---|
1188 |
|
---|
1189 | =========================== ========= ======== ==========
|
---|
1190 | Method PostGIS Oracle SpatiaLite
|
---|
1191 | =========================== ========= ======== ==========
|
---|
1192 | ``area`` X X X
|
---|
1193 | ``centroid`` X X X
|
---|
1194 | ``collect`` X
|
---|
1195 | ``difference`` X X X
|
---|
1196 | ``distance`` X X X
|
---|
1197 | ``envelope`` X X
|
---|
1198 | ``extent`` X X
|
---|
1199 | ``extent3d`` X
|
---|
1200 | ``geojson`` X
|
---|
1201 | ``gml`` X X
|
---|
1202 | ``intersection`` X X X
|
---|
1203 | ``kml`` X
|
---|
1204 | ``length`` X X X
|
---|
1205 | ``make_line`` X
|
---|
1206 | ``mem_size`` X
|
---|
1207 | ``num_geom`` X X X
|
---|
1208 | ``num_points`` X X X
|
---|
1209 | ``perimeter`` X X
|
---|
1210 | ``point_on_surface`` X X X
|
---|
1211 | ``scale`` X X
|
---|
1212 | ``snap_to_grid`` X
|
---|
1213 | ``svg`` X X
|
---|
1214 | ``sym_difference`` X X X
|
---|
1215 | ``transform`` X X X
|
---|
1216 | ``translate`` X X
|
---|
1217 | ``union`` X X X
|
---|
1218 | ``unionagg`` X X X
|
---|
1219 | =========================== ========= ======== ==========
|
---|
1220 |
|
---|
1221 | .. rubric:: Footnotes
|
---|
1222 | .. [#] *See* Open Geospatial Consortium, Inc., `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, Document 99-049 (May 5, 1999), at Ch. 3.2.5, p. 3-11 (SQL Textual Representation of Geometry).
|
---|
1223 | .. [#] *See* `PostGIS EWKB, EWKT and Canonical Forms <http://postgis.refractions.net/documentation/manual-1.3/ch04.html#id2571020>`_, PostGIS documentation at Ch. 4.1.2.
|
---|
1224 | .. [#] *See* Howard Butler, Martin Daly, Allan Doyle, Tim Schaub, & Christopher Schmidt, `The GeoJSON Format Specification <http://geojson.org/geojson-spec.html>`_, Revision 1.0 (June 16, 2008).
|
---|
1225 | .. [#] *See generally*, `Operators <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2576880>`_, PostGIS Documentation at Ch. 6.2.2.
|
---|
1226 | .. [#] *See generally*, `Geometry Relationship Functions <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2574517>`_ PostGIS Documentation at Ch. 6.1.2.
|
---|
1227 | .. [#] For an explanation of this routine, see `this entry <http://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html>`_ at the blog of Martin Davis (a PostGIS developer).
|
---|
1228 | .. [#] *See id.*
|
---|
1229 | .. [#] *See* `OpenGIS Simple Feature Specification For SQL <http://www.opengis.org/docs/99-049.pdf>`_, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
|
---|
1230 | .. [#] Oracle Spatial User's Guide and Manual, at Ch. 11.
|
---|
1231 | .. [#] *See id.* at `SDO_RELATE documentation <http://download.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_.
|
---|
1232 | .. [#] MySQL 5.0 Reference Manual, at Ch. 17.5.5.
|
---|
1233 | .. [#] *See* the `distance documentation`_ for more information on the ``Distance`` object.
|
---|
1234 | .. [#] *See* ``ST_distance_sphere`` in `Measurement Functions <http://postgis.refractions.net/documentation/manual-1.3/ch06.html#id2577138>`_, PostGIS documentation at Ch. 6.2.3.
|
---|
1235 | .. [#] MySQL only supports bounding box operations (known as minimum bounding rectangles, or MBR, in MySQL). Thus, spatial lookups such as ``contains`` are really equivalent to ``bbcontains``.
|
---|