PageRenderTime 391ms CodeModel.GetById 101ms app.highlight 119ms RepoModel.GetById 93ms app.codeStats 1ms

/docs/ref/contrib/gis/geoquerysets.txt

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