mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-04 19:08:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Removed GeoManager and GeoQuerySet per deprecation timeline.

Browse source
This commit is contained in:
Tim Graham 2016-11-07 13:00:40 +01:00
parent e90c745afd
commit a0d166306f
25 changed files with 32 additions and 2194 deletions
Download patch file Download diff file Expand all files Collapse all files

595
docs/ref/contrib/gis/geoquerysets.txt
View file

@ -1,11 +1,9 @@
=========================
GeoQuerySet API Reference
=========================
==========================
GIS QuerySet API Reference
==========================
.. currentmodule:: django.contrib.gis.db.models
.. class:: GeoQuerySet(model=None)
.. _spatial-lookups:
Spatial Lookups
@ -720,593 +718,6 @@ SpatiaLite ``PtDistWithin(poly, geom, 5)``
SpatiaLite support was added.
.. _geoqueryset-methods:
``GeoQuerySet`` Methods
=======================
.. deprecated:: 1.9
Using ``GeoQuerySet`` methods is now deprecated in favor of the new
:doc:`functions`. Albeit a little more verbose, they are much more powerful
in how it is possible to combine them to build more complex queries.
``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 <database-functions-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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Area` function
instead.
Returns the area of the geographic field in an ``area`` attribute on
each element of this GeoQuerySet.
``distance``
~~~~~~~~~~~~
.. method:: GeoQuerySet.distance(geom, **kwargs)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Distance` function
instead.
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
__ https://en.wikipedia.org/wiki/Tasmania
``length``
~~~~~~~~~~
.. method:: GeoQuerySet.length(**kwargs)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Length` function
instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Perimeter` function
instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Centroid` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Envelope` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.PointOnSurface`
function instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.ForceRHR` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Reverse` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Scale` function
instead.
*Availability*: PostGIS, SpatiaLite
``snap_to_grid``
~~~~~~~~~~~~~~~~
.. method:: GeoQuerySet.snap_to_grid(*args, **kwargs)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.SnapToGrid` function
instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Transform` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Translate` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Difference` function
instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Intersection`
function instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.SymDifference`
function instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.Union` function
instead.
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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.GeoHash` function
instead.
Attaches a ``geohash`` attribute to every model the queryset
containing the `GeoHash`__ representation of the geometry.
__ http://geohash.org/
``geojson``
~~~~~~~~~~~
.. method:: GeoQuerySet.geojson(**kwargs)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.AsGeoJSON` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.AsGML` function
instead.
*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.
===================== =====================================================
__ https://en.wikipedia.org/wiki/Geography_Markup_Language
``kml``
~~~~~~~
.. method:: GeoQuerySet.kml(**kwargs)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.AsKML` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.AsSVG` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.MemSize` function
instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.NumGeometries`
function instead.
*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)
.. deprecated:: 1.9
Use the :class:`~django.contrib.gis.db.models.functions.NumPoints` function
instead.
*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``.
Aggregate Functions
-------------------