mirror of
https://github.com/django/django.git
synced 2024-12-30 21:16:26 +00:00
1265 lines
36 KiB
Plaintext
1265 lines
36 KiB
Plaintext
=========================
|
|
GeoQuerySet API Reference
|
|
=========================
|
|
|
|
.. currentmodule:: django.contrib.gis.db.models
|
|
|
|
.. class:: GeoQuerySet([model=None])
|
|
|
|
.. _spatial-lookups:
|
|
|
|
Spatial Lookups
|
|
===============
|
|
|
|
Just like when using the :ref:`queryset-api`, interaction
|
|
with ``GeoQuerySet`` by :ref:`chaining filters <chaining-filters>`.
|
|
Instead of the regular Django :ref:`field-lookups`, the
|
|
spatial lookups in this section are available for :class:`GeometryField`.
|
|
|
|
For an introduction, see the :ref:`spatial lookups introduction
|
|
<spatial-lookups-intro>`. For an overview of what lookups are
|
|
compatible with a particular spatial backend, refer to the
|
|
:ref:`spatial lookup compatibility table <spatial-lookup-compatibility>`.
|
|
|
|
.. fieldlookup:: bbcontains
|
|
|
|
bbcontains
|
|
----------
|
|
|
|
*Availability*: PostGIS, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field's bounding box completely contains the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__bbcontains=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly ~ geom``
|
|
MySQL ``MBRContains(poly, geom)``
|
|
SpatiaLite ``MbrContains(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: bboverlaps
|
|
|
|
bboverlaps
|
|
----------
|
|
|
|
*Availability*: PostGIS, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field's bounding box overlaps the lookup geometry's
|
|
bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__bboverlaps=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly && geom``
|
|
MySQL ``MBROverlaps(poly, geom)``
|
|
SpatiaLite ``MbrOverlaps(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: contained
|
|
|
|
contained
|
|
---------
|
|
|
|
*Availability*: PostGIS, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field's bounding box is completely contained by the
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contained=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``poly @ geom``
|
|
MySQL ``MBRWithin(poly, geom)``
|
|
SpatiaLite ``MbrWithin(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: gis-contains
|
|
|
|
contains
|
|
--------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field spatially contains the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contains=geom)
|
|
|
|
========== ============================
|
|
Backend SQL Equivalent
|
|
========== ============================
|
|
PostGIS ``ST_Contains(poly, geom)``
|
|
Oracle ``SDO_CONTAINS(poly, geom)``
|
|
MySQL ``MBRContains(poly, geom)``
|
|
SpatiaLite ``Contains(poly, geom)``
|
|
========== ============================
|
|
|
|
.. fieldlookup:: contains_properly
|
|
|
|
contains_properly
|
|
-----------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Returns true if the lookup geometry intersects the interior of the
|
|
geometry field, but not the boundary (or exterior). [#fncontainsproperly]_
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__contains_properly=geom)
|
|
|
|
========== ===================================
|
|
Backend SQL Equivalent
|
|
========== ===================================
|
|
PostGIS ``ST_ContainsProperly(poly, geom)``
|
|
========== ===================================
|
|
|
|
.. fieldlookup:: coveredby
|
|
|
|
coveredby
|
|
---------
|
|
|
|
*Availability*: PostGIS, Oracle
|
|
|
|
Tests if no point in the geometry field is outside the lookup geometry.
|
|
[#fncovers]_
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__coveredby=geom)
|
|
|
|
========== =============================
|
|
Backend SQL Equivalent
|
|
========== =============================
|
|
PostGIS ``ST_CoveredBy(poly, geom)``
|
|
Oracle ``SDO_COVEREDBY(poly, geom)``
|
|
========== =============================
|
|
|
|
.. fieldlookup:: covers
|
|
|
|
covers
|
|
------
|
|
|
|
*Availability*: PostGIS, Oracle
|
|
|
|
Tests if no point in the lookup geometry is outside the geometry field.
|
|
[#fncovers]_
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__covers=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Covers(poly, geom)``
|
|
Oracle ``SDO_COVERS(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: crosses
|
|
|
|
crosses
|
|
-------
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Tests if the geometry field spatially crosses the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__crosses=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Crosses(poly, geom)``
|
|
SpatiaLite ``Crosses(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: disjoint
|
|
|
|
disjoint
|
|
--------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field is spatially disjoint from the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__disjoint=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``ST_Disjoint(poly, geom)``
|
|
Oracle ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)``
|
|
MySQL ``MBRDisjoint(poly, geom)``
|
|
SpatiaLite ``Disjoint(poly, geom)``
|
|
========== =================================================
|
|
|
|
equals
|
|
------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
.. fieldlookup:: exact
|
|
.. fieldlookup:: same_as
|
|
|
|
exact, same_as
|
|
--------------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
.. fieldlookup:: intersects
|
|
|
|
intersects
|
|
----------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field spatially intersects the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__intersects=geom)
|
|
|
|
========== =================================================
|
|
Backend SQL Equivalent
|
|
========== =================================================
|
|
PostGIS ``ST_Intersects(poly, geom)``
|
|
Oracle ``SDO_OVERLAPBDYINTERSECT(poly, geom)``
|
|
MySQL ``MBRIntersects(poly, geom)``
|
|
SpatiaLite ``Intersects(poly, geom)``
|
|
========== =================================================
|
|
|
|
.. fieldlookup:: overlaps
|
|
|
|
overlaps
|
|
--------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
.. fieldlookup:: relate
|
|
|
|
relate
|
|
------
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Tests if the geometry field is spatially related to the lookup geometry by
|
|
the values given in the given pattern. This lookup requires a tuple parameter,
|
|
``(geom, pattern)``; the form of ``pattern`` will depend on the spatial backend:
|
|
|
|
PostGIS & SpatiaLite
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
On these spatial backends the intersection pattern is a string comprising
|
|
nine characters, which define intersections between the interior, boundary,
|
|
and exterior of the geometry field and the lookup geometry.
|
|
The intersection pattern matrix may only use the following characters:
|
|
``1``, ``2``, ``T``, ``F``, or ``*``. This lookup type allows users to "fine tune"
|
|
a specific geometric relationship consistent with the DE-9IM model. [#fnde9im]_
|
|
|
|
Example::
|
|
|
|
# A tuple lookup parameter is used to specify the geometry and
|
|
# the intersection pattern (the pattern here is for 'contains').
|
|
Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))
|
|
|
|
PostGIS SQL equivalent::
|
|
|
|
SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')
|
|
|
|
SpatiaLite SQL equivalent::
|
|
|
|
SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')
|
|
|
|
Oracle
|
|
~~~~~~
|
|
|
|
Here the relation pattern is comprised at least one of the nine relation
|
|
strings: ``TOUCH``, ``OVERLAPBDYDISJOINT``, ``OVERLAPBDYINTERSECT``,
|
|
``EQUAL``, ``INSIDE``, ``COVEREDBY``, ``CONTAINS``, ``COVERS``, ``ON``, and
|
|
``ANYINTERACT``. Multiple strings may be combined with the logical Boolean
|
|
operator OR, for example, ``'inside+touch'``. [#fnsdorelate]_ The relation
|
|
strings are case-insensitive.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))
|
|
|
|
Oracle SQL equivalent::
|
|
|
|
SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
|
|
|
|
.. fieldlookup:: touches
|
|
|
|
touches
|
|
-------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field spatially touches the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__touches=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Touches(poly, geom)``
|
|
MySQL ``MBRTouches(poly, geom)``
|
|
Oracle ``SDO_TOUCH(poly, geom)``
|
|
SpatiaLite ``Touches(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: within
|
|
|
|
within
|
|
------
|
|
|
|
*Availability*: PostGIS, Oracle, MySQL, SpatiaLite
|
|
|
|
Tests if the geometry field is spatially within the lookup geometry.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__within=geom)
|
|
|
|
========== ==========================
|
|
Backend SQL Equivalent
|
|
========== ==========================
|
|
PostGIS ``ST_Within(poly, geom)``
|
|
MySQL ``MBRWithin(poly, geom)``
|
|
Oracle ``SDO_INSIDE(poly, geom)``
|
|
SpatiaLite ``Within(poly, geom)``
|
|
========== ==========================
|
|
|
|
.. fieldlookup:: left
|
|
|
|
left
|
|
----
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box is strictly to the left of the
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__left=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly << geom
|
|
|
|
.. fieldlookup:: right
|
|
|
|
right
|
|
-----
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box is strictly to the right of the
|
|
lookup geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__right=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly >> geom
|
|
|
|
.. fieldlookup:: overlaps_left
|
|
|
|
overlaps_left
|
|
-------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box overlaps or is to the left of the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_left=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly &< geom
|
|
|
|
|
|
.. fieldlookup:: overlaps_right
|
|
|
|
overlaps_right
|
|
--------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box overlaps or is to the right of the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_right=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly &> geom
|
|
|
|
.. fieldlookup:: overlaps_above
|
|
|
|
overlaps_above
|
|
--------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box overlaps or is above the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_above=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly |&> geom
|
|
|
|
.. fieldlookup:: overlaps_below
|
|
|
|
overlaps_below
|
|
--------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box overlaps or is below the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__overlaps_below=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly &<| geom
|
|
|
|
.. fieldlookup:: strictly_above
|
|
|
|
strictly_above
|
|
--------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box is strictly above the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__strictly_above=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly |>> geom
|
|
|
|
.. fieldlookup:: strictly_below
|
|
|
|
strictly_below
|
|
--------------
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Tests if the geometry field's bounding box is strictly below the lookup
|
|
geometry's bounding box.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__strictly_below=geom)
|
|
|
|
PostGIS equivalent::
|
|
|
|
SELECT ... WHERE poly <<| geom
|
|
|
|
|
|
.. _distance-lookups:
|
|
|
|
Distance Lookups
|
|
================
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
For an overview on performing distance queries, please refer to
|
|
the :ref:`distance queries introduction <distance-queries>`.
|
|
|
|
Distance lookups take the following form::
|
|
|
|
<field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid'])
|
|
|
|
The value passed into a distance lookup is a tuple; the first two
|
|
values are mandatory, and are the geometry to calculate distances to,
|
|
and a distance value (either a number in units of the field or a
|
|
:class:`~django.contrib.gis.measure.Distance` object). On every
|
|
distance lookup but :lookup:`dwithin`, an optional
|
|
third element, ``'spheroid'``, may be included to tell GeoDjango
|
|
to use the more accurate spheroid distance calculation functions on
|
|
fields with a geodetic coordinate system (e.g., ``ST_Distance_Spheroid``
|
|
would be used instead of ``ST_Distance_Sphere``).
|
|
|
|
.. fieldlookup:: distance_gt
|
|
|
|
distance_gt
|
|
-----------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is greater than the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
|
|
|
|
========== ===============================================
|
|
Backend SQL Equivalent
|
|
========== ===============================================
|
|
PostGIS ``ST_Distance(poly, geom) > 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5``
|
|
SpatiaLite ``Distance(poly, geom) > 5``
|
|
========== ===============================================
|
|
|
|
.. fieldlookup:: distance_gte
|
|
|
|
distance_gte
|
|
------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is greater than or equal to the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
|
|
|
|
========== ================================================
|
|
Backend SQL Equivalent
|
|
========== ================================================
|
|
PostGIS ``ST_Distance(poly, geom) >= 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5``
|
|
SpatiaLite ``Distance(poly, geom) >= 5``
|
|
========== ================================================
|
|
|
|
.. fieldlookup:: distance_lt
|
|
|
|
distance_lt
|
|
-----------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is less than the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
|
|
|
|
========== ===============================================
|
|
Backend SQL Equivalent
|
|
========== ===============================================
|
|
PostGIS ``ST_Distance(poly, geom) < 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5``
|
|
SpatiaLite ``Distance(poly, geom) < 5``
|
|
========== ===============================================
|
|
|
|
.. fieldlookup:: distance_lte
|
|
|
|
distance_lte
|
|
------------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry is less than or equal to the given distance value.
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
|
|
|
|
========== ================================================
|
|
Backend SQL Equivalent
|
|
========== ================================================
|
|
PostGIS ``ST_Distance(poly, geom) <= 5``
|
|
Oracle ``SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5``
|
|
SpatiaLite ``Distance(poly, geom) <= 5``
|
|
========== ================================================
|
|
|
|
.. fieldlookup:: dwithin
|
|
|
|
dwithin
|
|
-------
|
|
|
|
Returns models where the distance to the geometry field from the lookup
|
|
geometry are within the given distance from one another. Note that you can only
|
|
provide :class:`~django.contrib.gis.measure.Distance` objects if the targeted
|
|
geometries are in a projected system. For geographic geometries, you should use
|
|
units of the geometry field (e.g. degrees for ``WGS84``) .
|
|
|
|
Example::
|
|
|
|
Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
|
|
|
|
========== ======================================
|
|
Backend SQL Equivalent
|
|
========== ======================================
|
|
PostGIS ``ST_DWithin(poly, geom, 5)``
|
|
Oracle ``SDO_WITHIN_DISTANCE(poly, geom, 5)``
|
|
========== ======================================
|
|
|
|
.. note::
|
|
|
|
This lookup is not available on SpatiaLite.
|
|
|
|
.. fieldlookup:: equals
|
|
|
|
|
|
``GeoQuerySet`` Methods
|
|
=======================
|
|
|
|
``GeoQuerySet`` methods specify that a spatial operation be performed
|
|
on each spatial operation on each geographic
|
|
field in the queryset and store its output in a new attribute on the model
|
|
(which is generally the name of the ``GeoQuerySet`` method).
|
|
|
|
There are also aggregate ``GeoQuerySet`` methods which return a single value
|
|
instead of a queryset. This section will describe the API and availability
|
|
of every ``GeoQuerySet`` method available in GeoDjango.
|
|
|
|
.. note::
|
|
|
|
What methods are available depend on your spatial backend. See
|
|
the :ref:`compatibility table <geoqueryset-method-compatibility>`
|
|
for more details.
|
|
|
|
With a few exceptions, the following keyword arguments may be used with all
|
|
``GeoQuerySet`` methods:
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``field_name`` By default, ``GeoQuerySet`` methods use the first
|
|
geographic field encountered in the model. This
|
|
keyword should be used to specify another
|
|
geographic field (e.g., ``field_name='point2'``)
|
|
when there are multiple geographic fields in a model.
|
|
|
|
On PostGIS, the ``field_name`` keyword may also be
|
|
used on geometry fields in models that are related
|
|
via a ``ForeignKey`` relation (e.g.,
|
|
``field_name='related__point'``).
|
|
|
|
``model_att`` By default, ``GeoQuerySet`` methods typically attach
|
|
their output in an attribute with the same name as
|
|
the ``GeoQuerySet`` method. Setting this keyword
|
|
with the desired attribute name will override this
|
|
default behavior. For example,
|
|
``qs = Zipcode.objects.centroid(model_att='c')`` will
|
|
attach the centroid of the ``Zipcode`` geometry field
|
|
in a ``c`` attribute on every model rather than in a
|
|
``centroid`` attribute.
|
|
|
|
This keyword is required if
|
|
a method name clashes with an existing
|
|
``GeoQuerySet`` method -- if you wanted to use the
|
|
``area()`` method on model with a ``PolygonField``
|
|
named ``area``, for example.
|
|
===================== =====================================================
|
|
|
|
Measurement
|
|
-----------
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
``area``
|
|
~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.area(**kwargs)
|
|
|
|
Returns the area of the geographic field in an ``area`` attribute on
|
|
each element of this GeoQuerySet.
|
|
|
|
``distance``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.distance(geom, **kwargs)
|
|
|
|
This method takes a geometry as a parameter, and attaches a ``distance``
|
|
attribute to every model in the returned queryset that contains the
|
|
distance (as a :class:`~django.contrib.gis.measure.Distance` object) to the given geometry.
|
|
|
|
In the following example (taken from the `GeoDjango distance tests`__),
|
|
the distance from the `Tasmanian`__ city of Hobart to every other
|
|
:class:`PointField` in the ``AustraliaCity`` queryset is calculated::
|
|
|
|
>>> pnt = AustraliaCity.objects.get(name='Hobart').point
|
|
>>> for city in AustraliaCity.objects.distance(pnt): print(city.name, city.distance)
|
|
Wollongong 990071.220408 m
|
|
Shellharbour 972804.613941 m
|
|
Thirroul 1002334.36351 m
|
|
Mittagong 975691.632637 m
|
|
Batemans Bay 834342.185561 m
|
|
Canberra 598140.268959 m
|
|
Melbourne 575337.765042 m
|
|
Sydney 1056978.87363 m
|
|
Hobart 0.0 m
|
|
Adelaide 1162031.83522 m
|
|
Hillsdale 1049200.46122 m
|
|
|
|
.. note::
|
|
|
|
Because the ``distance`` attribute is a
|
|
:class:`~django.contrib.gis.measure.Distance` object, you can easily express
|
|
the value in the units of your choice. For example, ``city.distance.mi`` is
|
|
the distance value in miles and ``city.distance.km`` is the distance value
|
|
in kilometers. See :doc:`measure` for usage details and the list of
|
|
:ref:`supported_units`.
|
|
|
|
__ https://github.com/django/django/blob/master/tests/gis_tests/distapp/models.py
|
|
__ http://en.wikipedia.org/wiki/Tasmania
|
|
|
|
``length``
|
|
~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.length(**kwargs)
|
|
|
|
Returns the length of the geometry field in a ``length`` attribute
|
|
(a :class:`~django.contrib.gis.measure.Distance` object) on each model in
|
|
the queryset.
|
|
|
|
``perimeter``
|
|
~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.perimeter(**kwargs)
|
|
|
|
Returns the perimeter of the geometry field in a ``perimeter`` attribute
|
|
(a :class:`~django.contrib.gis.measure.Distance` object) on each model in
|
|
the queryset.
|
|
|
|
Geometry Relationships
|
|
----------------------
|
|
|
|
The following methods take no arguments, and attach geometry objects
|
|
each element of the :class:`GeoQuerySet` that is the result of relationship
|
|
function evaluated on the geometry field.
|
|
|
|
``centroid``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.centroid(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Returns the ``centroid`` value for the geographic field in a ``centroid``
|
|
attribute on each element of the ``GeoQuerySet``.
|
|
|
|
``envelope``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.envelope(**kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Returns a geometry representing the bounding box of the geometry field in
|
|
an ``envelope`` attribute on each element of the ``GeoQuerySet``.
|
|
|
|
``point_on_surface``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.point_on_surface(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Returns a Point geometry guaranteed to lie on the surface of the
|
|
geometry field in a ``point_on_surface`` attribute on each element
|
|
of the queryset; otherwise sets with None.
|
|
|
|
Geometry Editors
|
|
----------------
|
|
|
|
``force_rhr``
|
|
~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.force_rhr(**kwargs)
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Returns a modified version of the polygon/multipolygon in which all
|
|
of the vertices follow the Right-Hand-Rule, and attaches as a
|
|
``force_rhr`` attribute on each element of the queryset.
|
|
|
|
``reverse_geom``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.reverse_geom(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle
|
|
|
|
Reverse the coordinate order of the geometry field, and attaches as a
|
|
``reverse`` attribute on each element of the queryset.
|
|
|
|
``scale``
|
|
~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.scale(x, y, z=0.0, **kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
``snap_to_grid``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.snap_to_grid(*args, **kwargs)
|
|
|
|
Snap all points of the input geometry to the grid. How the
|
|
geometry is snapped to the grid depends on how many numeric
|
|
(either float, integer, or long) arguments are given.
|
|
|
|
=================== =====================================================
|
|
Number of Arguments Description
|
|
=================== =====================================================
|
|
1 A single size to snap bot the X and Y grids to.
|
|
2 X and Y sizes to snap the grid to.
|
|
4 X, Y sizes and the corresponding X, Y origins.
|
|
=================== =====================================================
|
|
|
|
``transform``
|
|
~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.transform(srid=4326, **kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
The ``transform`` method transforms the geometry field of a model to the spatial
|
|
reference system specified by the ``srid`` parameter. If no ``srid`` is given,
|
|
then 4326 (WGS84) is used by default.
|
|
|
|
.. note::
|
|
|
|
Unlike other ``GeoQuerySet`` methods, ``transform`` stores its output
|
|
"in-place". In other words, no new attribute for the transformed
|
|
geometry is placed on the models.
|
|
|
|
.. note::
|
|
|
|
What spatial reference system an integer SRID corresponds to may depend on
|
|
the spatial database used. In other words, the SRID numbers used for Oracle
|
|
are not necessarily the same as those used by PostGIS.
|
|
|
|
Example::
|
|
|
|
>>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
|
|
>>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
|
|
>>> print(qs[0].poly.srid)
|
|
32140
|
|
>>> print(qs[0].poly)
|
|
POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...
|
|
|
|
``translate``
|
|
~~~~~~~~~~~~~
|
|
.. method:: GeoQuerySet.translate(x, y, z=0.0, **kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Translates the geometry field to a new location using the given numeric
|
|
parameters as offsets.
|
|
|
|
Geometry Operations
|
|
-------------------
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
The following methods all take a geometry as a parameter and attach a geometry
|
|
to each element of the ``GeoQuerySet`` that is the result of the operation.
|
|
|
|
``difference``
|
|
~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.difference(geom)
|
|
|
|
Returns the spatial difference of the geographic field with the given
|
|
geometry in a ``difference`` attribute on each element of the
|
|
``GeoQuerySet``.
|
|
|
|
|
|
``intersection``
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.intersection(geom)
|
|
|
|
Returns the spatial intersection of the geographic field with the
|
|
given geometry in an ``intersection`` attribute on each element of the
|
|
``GeoQuerySet``.
|
|
|
|
``sym_difference``
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.sym_difference(geom)
|
|
|
|
Returns the symmetric difference of the geographic field with the
|
|
given geometry in a ``sym_difference`` attribute on each element of the
|
|
``GeoQuerySet``.
|
|
|
|
``union``
|
|
~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.union(geom)
|
|
|
|
Returns the union of the geographic field with the given
|
|
geometry in an ``union`` attribute on each element of the
|
|
``GeoQuerySet``.
|
|
|
|
Geometry Output
|
|
---------------
|
|
|
|
The following ``GeoQuerySet`` methods will return an attribute that has the value
|
|
of the geometry field in each model converted to the requested output format.
|
|
|
|
``geohash``
|
|
~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.geohash(precision=20, **kwargs)
|
|
|
|
Attaches a ``geohash`` attribute to every model the queryset
|
|
containing the `GeoHash`__ representation of the geometry.
|
|
|
|
__ http://geohash.org/
|
|
|
|
``geojson``
|
|
~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.geojson(**kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Attaches a ``geojson`` attribute to every model in the queryset that contains the
|
|
`GeoJSON`__ representation of the geometry.
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``precision`` It may be used to specify the number of significant
|
|
digits for the coordinates in the GeoJSON
|
|
representation -- the default value is 8.
|
|
|
|
``crs`` Set this to ``True`` if you want the coordinate
|
|
reference system to be included in the returned
|
|
GeoJSON.
|
|
|
|
``bbox`` Set this to ``True`` if you want the bounding box
|
|
to be included in the returned GeoJSON.
|
|
===================== =====================================================
|
|
|
|
__ http://geojson.org/
|
|
|
|
``gml``
|
|
~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.gml(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Attaches a ``gml`` attribute to every model in the queryset that contains the
|
|
`Geographic Markup Language (GML)`__ representation of the geometry.
|
|
|
|
Example::
|
|
|
|
>>> qs = Zipcode.objects.all().gml()
|
|
>>> print(qs[0].gml)
|
|
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ... -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``precision`` This keyword is for PostGIS only. It may be used
|
|
to specify the number of significant digits for the
|
|
coordinates in the GML representation -- the default
|
|
value is 8.
|
|
|
|
``version`` This keyword is for PostGIS only. It may be used to
|
|
specify the GML version used, and may only be values
|
|
of 2 or 3. The default value is 2.
|
|
===================== =====================================================
|
|
|
|
__ http://en.wikipedia.org/wiki/Geography_Markup_Language
|
|
|
|
``kml``
|
|
~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.kml(**kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Attaches a ``kml`` attribute to every model in the queryset that contains the
|
|
`Keyhole Markup Language (KML)`__ representation of the geometry fields. It
|
|
should be noted that the contents of the KML are transformed to WGS84 if
|
|
necessary.
|
|
|
|
Example::
|
|
|
|
>>> qs = Zipcode.objects.all().kml()
|
|
>>> print(qs[0].kml)
|
|
<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``precision`` This keyword may be used to specify the number of
|
|
significant digits for the coordinates in the KML
|
|
representation -- the default value is 8.
|
|
===================== =====================================================
|
|
|
|
__ https://developers.google.com/kml/documentation/
|
|
|
|
``svg``
|
|
~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.svg(**kwargs)
|
|
|
|
*Availability*: PostGIS, SpatiaLite
|
|
|
|
Attaches a ``svg`` attribute to every model in the queryset that contains
|
|
the `Scalable Vector Graphics (SVG)`__ path data of the geometry fields.
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``relative`` If set to ``True``, the path data will be implemented
|
|
in terms of relative moves. Defaults to ``False``,
|
|
meaning that absolute moves are used instead.
|
|
|
|
``precision`` This keyword may be used to specify the number of
|
|
significant digits for the coordinates in the SVG
|
|
representation -- the default value is 8.
|
|
===================== =====================================================
|
|
|
|
__ http://www.w3.org/Graphics/SVG/
|
|
|
|
Miscellaneous
|
|
-------------
|
|
|
|
``mem_size``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.mem_size(**kwargs)
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Returns the memory size (number of bytes) that the geometry field takes
|
|
in a ``mem_size`` attribute on each element of the ``GeoQuerySet``.
|
|
|
|
``num_geom``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.num_geom(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Returns the number of geometries in a ``num_geom`` attribute on
|
|
each element of the ``GeoQuerySet`` if the geometry field is a
|
|
collection (e.g., a ``GEOMETRYCOLLECTION`` or ``MULTI*`` field);
|
|
otherwise sets with ``None``.
|
|
|
|
``num_points``
|
|
~~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.num_points(**kwargs)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
Returns the number of points in the first linestring in the
|
|
geometry field in a ``num_points`` attribute on each element of
|
|
the ``GeoQuerySet``; otherwise sets with ``None``.
|
|
|
|
Spatial Aggregates
|
|
==================
|
|
|
|
Aggregate Methods
|
|
-----------------
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Aggregate methods are now deprecated. Prefer using their function-based
|
|
equivalents.
|
|
|
|
``collect``
|
|
~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.collect(**kwargs)
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Use the :class:`Collect` aggregate instead.
|
|
|
|
Shortcut for ``aggregate(Collect(<field>))``.
|
|
|
|
``extent``
|
|
~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.extent(**kwargs)
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Use the :class:`Extent` aggregate instead.
|
|
|
|
Shortcut for ``aggregate(Extent(<field>))``.
|
|
|
|
``extent3d``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.extent3d(**kwargs)
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Use the :class:`Extent` aggregate instead.
|
|
|
|
Shortcut for ``aggregate(Extent3D(<field>))``.
|
|
|
|
``make_line``
|
|
~~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.make_line(**kwargs)
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Use the :class:`MakeLine` aggregate instead.
|
|
|
|
Shortcut for ``aggregate(MakeLine(<field>))``.
|
|
|
|
``unionagg``
|
|
~~~~~~~~~~~~
|
|
|
|
.. method:: GeoQuerySet.unionagg(**kwargs)
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Use the :class:`Union` aggregate instead.
|
|
|
|
Shortcut for ``aggregate(Union(<field>))``.
|
|
|
|
Aggregate Functions
|
|
-------------------
|
|
|
|
Django provides some GIS-specific aggregate functions. For details on how to
|
|
use these aggregate functions, see :doc:`the topic guide on aggregation
|
|
</topics/db/aggregation>`.
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``tolerance`` This keyword is for Oracle only. It is for the
|
|
tolerance value used by the ``SDOAGGRTYPE``
|
|
procedure; the `Oracle documentation`__ has more
|
|
details.
|
|
===================== =====================================================
|
|
|
|
__ http://docs.oracle.com/html/B14255_01/sdo_intro.htm#sthref150
|
|
|
|
Example::
|
|
|
|
>>> from django.contrib.gis.db.models import Extent, Union
|
|
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))
|
|
|
|
``Collect``
|
|
~~~~~~~~~~~
|
|
|
|
.. class:: Collect(geo_field)
|
|
|
|
*Availability*: PostGIS, Spatialite (≥3.0)
|
|
|
|
Returns a ``GEOMETRYCOLLECTION`` or a ``MULTI`` geometry object from the geometry
|
|
column. This is analogous to a simplified version of the :class:`Union`
|
|
aggregate, except it can be several orders of magnitude faster than performing
|
|
a union because it simply rolls up geometries into a collection or multi object,
|
|
not caring about dissolving boundaries.
|
|
|
|
``Extent``
|
|
~~~~~~~~~~
|
|
|
|
.. class:: Extent(geo_field)
|
|
|
|
*Availability*: PostGIS, Oracle, Spatialite (≥3.0)
|
|
|
|
Returns the extent of all ``geo_field`` in the ``QuerySet`` as a four-tuple,
|
|
comprising the lower left coordinate and the upper right coordinate.
|
|
|
|
Example::
|
|
|
|
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
|
|
>>> print(qs[poly__extent])
|
|
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
|
|
|
|
``Extent3D``
|
|
~~~~~~~~~~~~
|
|
|
|
.. class:: Extent3D(geo_field)
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Returns the 3D extent of all ``geo_field`` in the ``QuerySet`` as a six-tuple,
|
|
comprising the lower left coordinate and upper right coordinate (each with x, y,
|
|
and z coordinates).
|
|
|
|
Example::
|
|
|
|
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly'))
|
|
>>> print(qs[poly__extent3d])
|
|
(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)
|
|
|
|
``MakeLine``
|
|
~~~~~~~~~~~~
|
|
|
|
.. class:: MakeLine(geo_field)
|
|
|
|
*Availability*: PostGIS
|
|
|
|
Returns a ``LineString`` constructed from the point field geometries in the
|
|
``QuerySet``. Currently, ordering the queryset has no effect.
|
|
|
|
Example::
|
|
|
|
>>> print(City.objects.filter(name__in=('Houston', 'Dallas')
|
|
... ).aggregate(MakeLine('poly'))[poly__makeline]
|
|
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)
|
|
|
|
``Union``
|
|
~~~~~~~~~
|
|
|
|
.. class:: Union(geo_field)
|
|
|
|
*Availability*: PostGIS, Oracle, SpatiaLite
|
|
|
|
This method returns a :class:`~django.contrib.gis.geos.GEOSGeometry` object
|
|
comprising the union of every geometry in the queryset. Please note that use of
|
|
``Union`` is processor intensive and may take a significant amount of time on
|
|
large querysets.
|
|
|
|
.. note::
|
|
|
|
If the computation time for using this method is too expensive, consider
|
|
using :class:`Collect` instead.
|
|
|
|
Example::
|
|
|
|
>>> u = Zipcode.objects.aggregate(Union(poly)) # This may take a long time.
|
|
>>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly)) # A more sensible approach.
|
|
|
|
.. rubric:: Footnotes
|
|
.. [#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).
|
|
.. [#fnsdorelate] *See* `SDO_RELATE documentation <http://docs.oracle.com/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#sthref845>`_, from Ch. 11 of the Oracle Spatial User's Guide and Manual.
|
|
.. [#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).
|
|
.. [#fncontainsproperly] Refer to the PostGIS ``ST_ContainsProperly`` `documentation <http://postgis.net/docs/manual-1.5/ST_ContainsProperly.html>`_ for more details.
|