← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal-security

« back to all changes in this revision

Viewing changes to docs/ref/contrib/gis/geoquerysets.txt

  • Committer: Bazaar Package Importer
  • Author(s): Jamie Strandboge
  • Date: 2010-10-12 11:34:35 UTC
  • mfrom: (1.2.7 upstream)
  • mto: This revision was merged to the branch mainline in revision 30.
  • Revision ID: james.westby@ubuntu.com-20101012113435-9lnsrh0i3mxozbt0
Tags: upstream-1.2.3
Import upstream version 1.2.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/contrib/gis/geoquerysets.txt
14
14
Spatial Lookups
15
15
===============
16
16
 
17
 
Just like when using the the :ref:`queryset-api`, interaction 
 
17
Just like when using the the :ref:`queryset-api`, interaction
18
18
with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`.
19
19
Instead of the regular Django :ref:`field-lookups`, the
20
20
spatial lookups in this section are available for :class:`GeometryField`.
21
21
 
22
 
For an introduction, see the :ref:`spatial lookups introduction 
 
22
For an introduction, see the :ref:`spatial lookups introduction
23
23
<spatial-lookups-intro>`.  For an overview of what lookups are
24
24
compatible with a particular spatial backend, refer to the
25
25
:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`.
31
31
 
32
32
*Availability*: PostGIS, MySQL, SpatiaLite
33
33
 
34
 
Tests if the geometry field's bounding box completely contains the lookup 
 
34
Tests if the geometry field's bounding box completely contains the lookup
35
35
geometry's bounding box.
36
36
 
37
37
Example::
53
53
 
54
54
*Availability*: PostGIS, MySQL, SpatiaLite
55
55
 
56
 
Tests if the geometry field's bounding box overlaps the lookup geometry's 
 
56
Tests if the geometry field's bounding box overlaps the lookup geometry's
57
57
bounding box.
58
58
 
59
59
Example::
277
277
 
278
278
PostGIS & SpatiaLite
279
279
~~~~~~~~~~~~~~~~~~~~
280
 
On these spatial backends the intersection pattern is a string comprising 
281
 
nine characters, which  define intersections between  the interior, boundary, 
282
 
and exterior of the geometry field and the lookup geometry.  
 
280
On these spatial backends the intersection pattern is a string comprising
 
281
nine characters, which  define intersections between  the interior, boundary,
 
282
and exterior of the geometry field and the lookup geometry.
283
283
The intersection pattern matrix may only use the following characters:
284
284
``1``, ``2``, ``T``, ``F``, or ``*``.  This lookup type allows users to "fine tune"
285
285
a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_
302
302
~~~~~~
303
303
 
304
304
Here the relation pattern is compreised at least one of the nine relation
305
 
strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``, 
 
305
strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
306
306
``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and
307
307
``ANYINTERACT``.   Multiple strings may be combined with the logical Boolean
308
308
operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_  The relation
312
312
 
313
313
    Zipcode.objects.filter(poly__relate(geom, 'anyinteract'))
314
314
 
315
 
Oracle SQL equivalent:: 
 
315
Oracle SQL equivalent::
316
316
 
317
317
    SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
318
318
 
403
403
 
404
404
*Availability*: PostGIS
405
405
 
406
 
Tests if the geometry field's bounding box overlaps or is to the left of the lookup 
 
406
Tests if the geometry field's bounding box overlaps or is to the left of the lookup
407
407
geometry's bounding box.
408
408
 
409
409
Example::
422
422
 
423
423
*Availability*: PostGIS
424
424
 
425
 
Tests if the geometry field's bounding box overlaps or is to the right of the lookup 
 
425
Tests if the geometry field's bounding box overlaps or is to the right of the lookup
426
426
geometry's bounding box.
427
427
 
428
428
Example::
440
440
 
441
441
*Availability*: PostGIS
442
442
 
443
 
Tests if the geometry field's bounding box overlaps or is above the lookup 
 
443
Tests if the geometry field's bounding box overlaps or is above the lookup
444
444
geometry's bounding box.
445
445
 
446
446
Example::
458
458
 
459
459
*Availability*: PostGIS
460
460
 
461
 
Tests if the geometry field's bounding box overlaps or is below the lookup 
 
461
Tests if the geometry field's bounding box overlaps or is below the lookup
462
462
geometry's bounding box.
463
463
 
464
464
Example::
476
476
 
477
477
*Availability*: PostGIS
478
478
 
479
 
Tests if the geometry field's bounding box is strictly above the lookup 
 
479
Tests if the geometry field's bounding box is strictly above the lookup
480
480
geometry's bounding box.
481
481
 
482
482
Example::
494
494
 
495
495
*Availability*: PostGIS
496
496
 
497
 
Tests if the geometry field's bounding box is strictly above the lookup 
 
497
Tests if the geometry field's bounding box is strictly above the lookup
498
498
geometry's bounding box.
499
499
 
500
500
Example::
662
662
=====================  =====================================================
663
663
``field_name``         By default, ``GeoQuerySet`` methods use the first
664
664
                       geographic field encountered in the model.  This
665
 
                       keyword should be used to specify another 
 
665
                       keyword should be used to specify another
666
666
                       geographic field (e.g., ``field_name='point2'``)
667
667
                       when there are multiple geographic fields in a model.
668
668
 
670
670
                       used on geometry fields in models that are related
671
671
                       via a ``ForeignKey`` relation (e.g.,
672
672
                       ``field_name='related__point'``).
673
 
    
 
673
 
674
674
``model_att``          By default, ``GeoQuerySet`` methods typically attach
675
675
                       their output in an attribute with the same name as
676
676
                       the ``GeoQuerySet`` method.  Setting this keyword
679
679
                       ``qs = Zipcode.objects.centroid(model_att='c')`` will
680
680
                       attach the centroid of the ``Zipcode`` geometry field
681
681
                       in a ``c`` attribute on every model rather than in a
682
 
                       ``centroid`` attribute.  
 
682
                       ``centroid`` attribute.
683
683
 
684
 
                       This keyword is required if 
685
 
                       a method name clashes with an existing 
686
 
                       ``GeoQuerySet`` method -- if you wanted to use the 
687
 
                       ``area()`` method on model with a ``PolygonField`` 
 
684
                       This keyword is required if
 
685
                       a method name clashes with an existing
 
686
                       ``GeoQuerySet`` method -- if you wanted to use the
 
687
                       ``area()`` method on model with a ``PolygonField``
688
688
                       named ``area``, for example.
689
689
=====================  =====================================================
690
690
 
705
705
 
706
706
.. method:: GeoQuerySet.distance(geom, **kwargs)
707
707
 
708
 
This method takes a geometry as a parameter, and attaches a ``distance`` 
709
 
attribute to every model in the returned queryset that contains the 
 
708
This method takes a geometry as a parameter, and attaches a ``distance``
 
709
attribute to every model in the returned queryset that contains the
710
710
distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry.
711
711
 
712
 
In the following example (taken from the `GeoDjango distance tests`__), 
713
 
the distance from the `Tasmanian`__ city of Hobart to every other 
 
712
In the following example (taken from the `GeoDjango distance tests`__),
 
713
the distance from the `Tasmanian`__ city of Hobart to every other
714
714
:class:`PointField` in the ``AustraliaCity`` queryset is calculated::
715
715
 
716
716
    >>> pnt = AustraliaCity.objects.get(name='Hobart').point
732
732
    Because the ``distance`` attribute is a
733
733
    :class:`~django.contrib.gis.measure.Distance` object, you can easily express
734
734
    the value in the units of your choice.  For example, ``city.distance.mi`` is
735
 
    the distance value in miles and ``city.distance.km`` is the distance value 
 
735
    the distance value in miles and ``city.distance.km`` is the distance value
736
736
    in kilometers.  See the :ref:`ref-measure` for usage details and the list of
737
737
    :ref:`supported_units`.
738
738
 
867
867
    geometry is placed on the models.
868
868
 
869
869
.. note::
870
 
    
871
 
    What spatial reference system an integer SRID corresponds to may depend on 
872
 
    the spatial database used.  In other words, the SRID numbers used for Oracle 
 
870
 
 
871
    What spatial reference system an integer SRID corresponds to may depend on
 
872
    the spatial database used.  In other words, the SRID numbers used for Oracle
873
873
    are not necessarily the same as those used by PostGIS.
874
874
 
875
875
Example::
903
903
.. method:: GeoQuerySet.difference(geom)
904
904
 
905
905
Returns the spatial difference of the geographic field with the given
906
 
geometry in a ``difference`` attribute on each element of the 
 
906
geometry in a ``difference`` attribute on each element of the
907
907
``GeoQuerySet``.
908
908
 
909
909
 
913
913
.. method:: GeoQuerySet.intersection(geom)
914
914
 
915
915
Returns the spatial intersection of the geographic field with the
916
 
given geometry in an ``intersection`` attribute on each element of the 
 
916
given geometry in an ``intersection`` attribute on each element of the
917
917
``GeoQuerySet``.
918
918
 
919
919
``sym_difference``
937
937
Geometry Output
938
938
---------------
939
939
 
940
 
The following ``GeoQuerySet`` methods will return an attribute that has the value 
 
940
The following ``GeoQuerySet`` methods will return an attribute that has the value
941
941
of the geometry field in each model converted to the requested output format.
942
942
 
943
943
``geohash``
967
967
=====================  =====================================================
968
968
Keyword Argument       Description
969
969
=====================  =====================================================
970
 
``precision``          It may be used to specify the number of significant 
971
 
                       digits for the coordinates in the GeoJSON 
 
970
``precision``          It may be used to specify the number of significant
 
971
                       digits for the coordinates in the GeoJSON
972
972
                       representation -- the default value is 8.
973
973
 
974
974
``crs``                Set this to ``True`` if you want the coordinate
988
988
 
989
989
*Availability*: PostGIS, Oracle
990
990
 
991
 
Attaches a ``gml`` attribute to every model in the queryset that contains the 
992
 
`Geographic Markup Language (GML)`__ representation of the geometry. 
 
991
Attaches a ``gml`` attribute to every model in the queryset that contains the
 
992
`Geographic Markup Language (GML)`__ representation of the geometry.
993
993
 
994
994
Example::
995
995
 
1000
1000
=====================  =====================================================
1001
1001
Keyword Argument       Description
1002
1002
=====================  =====================================================
1003
 
``precision``          This keyword is for PostGIS only.  It may be used 
1004
 
                       to specify the number of significant digits for the 
1005
 
                       coordinates in the GML representation -- the default 
 
1003
``precision``          This keyword is for PostGIS only.  It may be used
 
1004
                       to specify the number of significant digits for the
 
1005
                       coordinates in the GML representation -- the default
1006
1006
                       value is 8.
1007
1007
 
1008
1008
``version``            This keyword is for PostGIS only.  It may be used to
1019
1019
 
1020
1020
*Availability*: PostGIS
1021
1021
 
1022
 
Attaches a ``kml`` attribute to every model in the queryset that contains the 
1023
 
`Keyhole Markup Language (KML)`__ representation of the geometry fields. It 
1024
 
should be noted that the contents of the KML are transformed to WGS84 if 
 
1022
Attaches a ``kml`` attribute to every model in the queryset that contains the
 
1023
`Keyhole Markup Language (KML)`__ representation of the geometry fields. It
 
1024
should be noted that the contents of the KML are transformed to WGS84 if
1025
1025
necessary.
1026
1026
 
1027
1027
Example::
1033
1033
=====================  =====================================================
1034
1034
Keyword Argument       Description
1035
1035
=====================  =====================================================
1036
 
``precision``          This keyword may be used to specify the number of 
1037
 
                       significant digits for the coordinates in the KML 
 
1036
``precision``          This keyword may be used to specify the number of
 
1037
                       significant digits for the coordinates in the KML
1038
1038
                       representation -- the default value is 8.
1039
1039
=====================  =====================================================
1040
1040
 
1054
1054
Keyword Argument       Description
1055
1055
=====================  =====================================================
1056
1056
``relative``           If set to ``True``, the path data will be implemented
1057
 
                       in terms of relative moves.  Defaults to ``False``, 
 
1057
                       in terms of relative moves.  Defaults to ``False``,
1058
1058
                       meaning that absolute moves are used instead.
1059
1059
 
1060
 
``precision``          This keyword may be used to specify the number of 
1061
 
                       significant digits for the coordinates in the SVG 
 
1060
``precision``          This keyword may be used to specify the number of
 
1061
                       significant digits for the coordinates in the SVG
1062
1062
                       representation -- the default value is 8.
1063
1063
=====================  =====================================================
1064
1064
 
1129
1129
 
1130
1130
*Availability*: PostGIS, Oracle
1131
1131
 
1132
 
Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the 
 
1132
Returns the extent of the ``GeoQuerySet`` as a four-tuple, comprising the
1133
1133
lower left coordinate and the upper right coordinate.
1134
1134
 
1135
1135
Example::
1163
1163
 
1164
1164
*Availability*: PostGIS
1165
1165
 
1166
 
Returns a ``LineString`` constructed from the point field geometries in the 
 
1166
Returns a ``LineString`` constructed from the point field geometries in the
1167
1167
``GeoQuerySet``.  Currently, ordering the queryset has no effect.
1168
1168
 
1169
1169
Example::
1184
1184
of time on large querysets.
1185
1185
 
1186
1186
.. note::
1187
 
  
 
1187
 
1188
1188
    If the computation time for using this method is too expensive,
1189
1189
    consider using :meth:`GeoQuerySet.collect` instead.
1190
1190
 
1191
1191
Example::
1192
 
    
 
1192
 
1193
1193
    >>> u = Zipcode.objects.unionagg() # This may take a long time.
1194
1194
    >>> u = Zipcode.objects.filter(poly__within=bbox).unionagg() # A more sensible approach.
1195
1195
 
1196
1196
=====================  =====================================================
1197
1197
Keyword Argument       Description
1198
1198
=====================  =====================================================
1199
 
``tolerance``          This keyword is for Oracle only.  It is for the 
 
1199
``tolerance``          This keyword is for Oracle only.  It is for the
1200
1200
                       tolerance value used by the ``SDOAGGRTYPE``
1201
 
                       procedure; the  `Oracle documentation`__ has more 
 
1201
                       procedure; the  `Oracle documentation`__ has more
1202
1202
                       details.
1203
1203
=====================  =====================================================
1204
1204
 
1205
 
__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150 
 
1205
__ http://download.oracle.com/docs/html/B14255_01/sdo_intro.htm#sthref150
1206
1206
 
1207
1207
Aggregate Functions
1208
1208
-------------------