mirror of https://github.com/django/django.git
556 lines
20 KiB
Plaintext
556 lines
20 KiB
Plaintext
=============================
|
|
Geographic Database Functions
|
|
=============================
|
|
|
|
.. module:: django.contrib.gis.db.models.functions
|
|
:synopsis: Geographic Database Functions
|
|
|
|
The functions documented on this page allow users to access geographic database
|
|
functions to be used in annotations, aggregations, or filters in Django.
|
|
|
|
Example::
|
|
|
|
>>> from django.contrib.gis.db.models.functions import Length
|
|
>>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)
|
|
|
|
Not all backends support all functions, so refer to the documentation of each
|
|
function to see if your database backend supports the function you want to use.
|
|
If you call a geographic function on a backend that doesn't support it, you'll
|
|
get a ``NotImplementedError`` exception.
|
|
|
|
Function's summary:
|
|
|
|
================== ======================== ====================== ======================= ================== =====================
|
|
Measurement Relationships Operations Editors Output format Miscellaneous
|
|
================== ======================== ====================== ======================= ================== =====================
|
|
:class:`Area` :class:`Azimuth` :class:`Difference` :class:`ForcePolygonCW` :class:`AsGeoJSON` :class:`IsValid`
|
|
:class:`Distance` :class:`BoundingCircle` :class:`Intersection` :class:`ForceRHR` :class:`AsGML` :class:`MemSize`
|
|
:class:`Length` :class:`Centroid` :class:`SymDifference` :class:`MakeValid` :class:`AsKML` :class:`NumGeometries`
|
|
:class:`Perimeter` :class:`Envelope` :class:`Union` :class:`Reverse` :class:`AsSVG` :class:`NumPoints`
|
|
.. :class:`LineLocatePoint` :class:`Scale` :class:`GeoHash`
|
|
.. :class:`PointOnSurface` :class:`SnapToGrid`
|
|
.. :class:`Transform`
|
|
.. :class:`Translate`
|
|
================== ======================== ====================== ======================= ================== =====================
|
|
|
|
``Area``
|
|
========
|
|
|
|
.. class:: Area(expression, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-polygon-property-functions.html#function_area>`__,
|
|
Oracle, `PostGIS <https://postgis.net/docs/ST_Area.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the area of the
|
|
field as an :class:`~django.contrib.gis.measure.Area` measure.
|
|
|
|
MySQL and SpatiaLite without LWGEOM don't support area calculations on
|
|
geographic SRSes.
|
|
|
|
``AsGeoJSON``
|
|
=============
|
|
|
|
.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-geojson-functions.html#function_st-asgeojson>`__ (≥ 5.7.5),
|
|
`PostGIS <https://postgis.net/docs/ST_AsGeoJSON.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a `GeoJSON
|
|
<http://geojson.org/>`_ representation of the geometry. Note that the result is
|
|
not a complete GeoJSON structure but only the ``geometry`` key content of a
|
|
GeoJSON structure. See also :doc:`/ref/contrib/gis/serializers`.
|
|
|
|
Example::
|
|
|
|
>>> City.objects.annotate(json=AsGeoJSON('point')).get(name='Chicago').json
|
|
{"type":"Point","coordinates":[-87.65018,41.85039]}
|
|
|
|
===================== =====================================================
|
|
Keyword Argument Description
|
|
===================== =====================================================
|
|
``bbox`` Set this to ``True`` if you want the bounding box
|
|
to be included in the returned GeoJSON.
|
|
|
|
``crs`` Set this to ``True`` if you want the coordinate
|
|
reference system to be included in the returned
|
|
GeoJSON. Ignored on MySQL.
|
|
|
|
``precision`` It may be used to specify the number of significant
|
|
digits for the coordinates in the GeoJSON
|
|
representation -- the default value is 8.
|
|
===================== =====================================================
|
|
|
|
``AsGML``
|
|
=========
|
|
|
|
.. class:: AsGML(expression, version=2, precision=8, **extra)
|
|
|
|
*Availability*: Oracle, `PostGIS <https://postgis.net/docs/ST_AsGML.html>`__,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a `Geographic Markup
|
|
Language (GML)`__ representation of the geometry.
|
|
|
|
Example::
|
|
|
|
>>> qs = Zipcode.objects.annotate(gml=AsGML('poly'))
|
|
>>> 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`` Specifies the number of significant digits for the
|
|
coordinates in the GML representation -- the default
|
|
value is 8. Ignored on Oracle.
|
|
|
|
``version`` Specifies the GML version to use: 2 (default) or 3.
|
|
===================== =====================================================
|
|
|
|
__ https://en.wikipedia.org/wiki/Geography_Markup_Language
|
|
|
|
``AsKML``
|
|
=========
|
|
|
|
.. class:: AsKML(expression, precision=8, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_AsKML.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a `Keyhole Markup
|
|
Language (KML)`__ representation of the geometry.
|
|
|
|
Example::
|
|
|
|
>>> qs = Zipcode.objects.annotate(kml=AsKML('poly'))
|
|
>>> 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/
|
|
|
|
``AsSVG``
|
|
=========
|
|
|
|
.. class:: AsSVG(expression, relative=False, precision=8, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_AsSVG.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a `Scalable Vector
|
|
Graphics (SVG)`__ representation of the geometry.
|
|
|
|
===================== =====================================================
|
|
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.
|
|
===================== =====================================================
|
|
|
|
__ https://www.w3.org/Graphics/SVG/
|
|
|
|
``Azimuth``
|
|
===========
|
|
|
|
.. class:: Azimuth(point_a, point_b, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Azimuth.html>`__,
|
|
SpatiaLite (LWGEOM)
|
|
|
|
Returns the azimuth in radians of the segment defined by the given point
|
|
geometries, or ``None`` if the two points are coincident. The azimuth is angle
|
|
referenced from north and is positive clockwise: north = ``0``; east = ``π/2``;
|
|
south = ``π``; west = ``3π/2``.
|
|
|
|
``BoundingCircle``
|
|
==================
|
|
|
|
.. class:: BoundingCircle(expression, num_seg=48, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_MinimumBoundingCircle.html>`__,
|
|
`Oracle <https://docs.oracle.com/database/121/SPATL/sdo_geom-sdo_mbc.htm#SPATL1554>`_
|
|
|
|
Accepts a single geographic field or expression and returns the smallest circle
|
|
polygon that can fully contain the geometry.
|
|
|
|
The ``num_seg`` parameter is used only on PostGIS.
|
|
|
|
``Centroid``
|
|
============
|
|
|
|
.. class:: Centroid(expression, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-polygon-property-functions.html#function_st-centroid>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Centroid.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the ``centroid``
|
|
value of the geometry.
|
|
|
|
``Difference``
|
|
==============
|
|
|
|
.. class:: Difference(expr1, expr2, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-difference>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Difference.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts two geographic fields or expressions and returns the geometric
|
|
difference, that is the part of geometry A that does not intersect with
|
|
geometry B.
|
|
|
|
``Distance``
|
|
============
|
|
|
|
.. class:: Distance(expr1, expr2, spheroid=None, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-relation-functions-object-shapes.html#function_st-distance>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Distance.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts two geographic fields or expressions and returns the distance between
|
|
them, as a :class:`~django.contrib.gis.measure.Distance` object. On MySQL, a raw
|
|
float value is returned when the coordinates are geodetic.
|
|
|
|
On backends that support distance calculation on geodetic coordinates, the
|
|
proper backend function is automatically chosen depending on the SRID value of
|
|
the geometries (e.g. `ST_DistanceSphere
|
|
<https://postgis.net/docs/ST_DistanceSphere.html>`__ on PostGIS).
|
|
|
|
When distances are calculated with geodetic (angular) coordinates, as is the
|
|
case with the default WGS84 (4326) SRID, you can set the ``spheroid`` keyword
|
|
argument to decide if the calculation should be based on a simple sphere (less
|
|
accurate, less resource-intensive) or on a spheroid (more accurate, more
|
|
resource-intensive).
|
|
|
|
In the following example, the distance from the city of Hobart to every other
|
|
:class:`~django.contrib.gis.db.models.PointField` in the ``AustraliaCity``
|
|
queryset is calculated::
|
|
|
|
>>> from django.contrib.gis.db.models.functions import Distance
|
|
>>> pnt = AustraliaCity.objects.get(name='Hobart').point
|
|
>>> for city in AustraliaCity.objects.annotate(distance=Distance('point', pnt)):
|
|
... print(city.name, city.distance)
|
|
Wollongong 990071.220408 m
|
|
Shellharbour 972804.613941 m
|
|
Thirroul 1002334.36351 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`.
|
|
|
|
``Envelope``
|
|
============
|
|
|
|
.. class:: Envelope(expression, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-general-property-functions.html#function_st-envelope>`__,
|
|
`Oracle
|
|
<https://docs.oracle.com/database/121/SPATL/sdo_geom-sdo_mbr.htm#GUID-646638D0-2C5F-490A-AF63-DE9B7A4C97C1__CHDJCEIH>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Envelope.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the geometry
|
|
representing the bounding box of the geometry.
|
|
|
|
.. versionchanged:: 2.2
|
|
|
|
Oracle support was added.
|
|
|
|
``ForcePolygonCW``
|
|
==================
|
|
|
|
.. class:: ForcePolygonCW(expression, **extra)
|
|
|
|
.. versionadded:: 2.1
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_ForcePolygonCW.html>`__,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a modified version
|
|
of the polygon/multipolygon in which all exterior rings are oriented clockwise
|
|
and all interior rings are oriented counterclockwise. Non-polygonal geometries
|
|
are returned unchanged.
|
|
|
|
``ForceRHR``
|
|
============
|
|
|
|
.. class:: ForceRHR(expression, **extra)
|
|
|
|
.. deprecated:: 2.1
|
|
|
|
Use :class:`ForcePolygonCW` instead.
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_ForceRHR.html>`__
|
|
|
|
Accepts a single geographic field or expression and returns a modified version
|
|
of the polygon/multipolygon in which all of the vertices follow the
|
|
right-hand rule.
|
|
|
|
``GeoHash``
|
|
===========
|
|
|
|
.. class:: GeoHash(expression, precision=None, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-geohash-functions.html#function_st-geohash>`__ (≥ 5.7.5),
|
|
`PostGIS <https://postgis.net/docs/ST_GeoHash.html>`__, SpatiaLite (LWGEOM)
|
|
|
|
Accepts a single geographic field or expression and returns a `GeoHash`__
|
|
representation of the geometry.
|
|
|
|
The ``precision`` keyword argument controls the number of characters in the
|
|
result.
|
|
|
|
__ https://en.wikipedia.org/wiki/Geohash
|
|
|
|
``Intersection``
|
|
================
|
|
|
|
.. class:: Intersection(expr1, expr2, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-intersection>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Intersection.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts two geographic fields or expressions and returns the geometric
|
|
intersection between them.
|
|
|
|
``IsValid``
|
|
===========
|
|
|
|
.. class:: IsValid(expr)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-convenience-functions.html#function_st-isvalid>`__ (≥ 5.7.5),
|
|
`PostGIS <https://postgis.net/docs/ST_IsValid.html>`__, Oracle, SpatiaLite (LWGEOM)
|
|
|
|
Accepts a geographic field or expression and tests if the value is well formed.
|
|
Returns ``True`` if its value is a valid geometry and ``False`` otherwise.
|
|
|
|
``Length``
|
|
==========
|
|
|
|
.. class:: Length(expression, spheroid=True, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-linestring-property-functions.html#function_st-length>`__,
|
|
Oracle, `PostGIS <https://postgis.net/docs/ST_Length.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic linestring or multilinestring field or expression
|
|
and returns its length as a :class:`~django.contrib.gis.measure.Distance`
|
|
measure.
|
|
|
|
On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can
|
|
specify if the calculation should be based on a simple sphere (less
|
|
accurate, less resource-intensive) or on a spheroid (more accurate, more
|
|
resource-intensive) with the ``spheroid`` keyword argument.
|
|
|
|
MySQL doesn't support length calculations on geographic SRSes.
|
|
|
|
``LineLocatePoint``
|
|
===================
|
|
|
|
.. class:: LineLocatePoint(linestring, point, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_LineLocatePoint.html>`__,
|
|
SpatiaLite
|
|
|
|
Returns a float between 0 and 1 representing the location of the closest point on
|
|
``linestring`` to the given ``point``, as a fraction of the 2D line length.
|
|
|
|
``MakeValid``
|
|
=============
|
|
|
|
.. class:: MakeValid(expr)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_MakeValid.html>`__,
|
|
SpatiaLite (LWGEOM)
|
|
|
|
Accepts a geographic field or expression and attempts to convert the value into
|
|
a valid geometry without losing any of the input vertices. Geometries that are
|
|
already valid are returned without changes. Simple polygons might become a
|
|
multipolygon and the result might be of lower dimension than the input.
|
|
|
|
``MemSize``
|
|
===========
|
|
|
|
.. class:: MemSize(expression, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_MemSize.html>`__
|
|
|
|
Accepts a single geographic field or expression and returns the memory size
|
|
(number of bytes) that the geometry field takes.
|
|
|
|
``NumGeometries``
|
|
=================
|
|
|
|
.. class:: NumGeometries(expression, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-geometrycollection-property-functions.html#function_st-numgeometries>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_NumGeometries.html>`__, Oracle,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the number of
|
|
geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION``
|
|
or ``MULTI*`` field). Returns 1 for single geometries.
|
|
|
|
On MySQL, returns ``None`` for single geometries.
|
|
|
|
``NumPoints``
|
|
=============
|
|
|
|
.. class:: NumPoints(expression, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/gis-linestring-property-functions.html#function_st-numpoints>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_NPoints.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the number of points
|
|
in a geometry.
|
|
|
|
On MySQL, returns ``None`` for any non-``LINESTRING`` geometry.
|
|
|
|
``Perimeter``
|
|
=============
|
|
|
|
.. class:: Perimeter(expression, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Perimeter.html>`__,
|
|
Oracle, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns the perimeter of the
|
|
geometry field as a :class:`~django.contrib.gis.measure.Distance` object.
|
|
|
|
``PointOnSurface``
|
|
==================
|
|
|
|
.. class:: PointOnSurface(expression, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_PointOnSurface.html>`__,
|
|
Oracle, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a ``Point`` geometry
|
|
guaranteed to lie on the surface of the field; otherwise returns ``None``.
|
|
|
|
``Reverse``
|
|
===========
|
|
|
|
.. class:: Reverse(expression, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Reverse.html>`__, Oracle,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a geometry with
|
|
reversed coordinates.
|
|
|
|
``Scale``
|
|
=========
|
|
|
|
.. class:: Scale(expression, x, y, z=0.0, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Scale.html>`__, SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a geometry with
|
|
scaled coordinates by multiplying them with the ``x``, ``y``, and optionally
|
|
``z`` parameters.
|
|
|
|
``SnapToGrid``
|
|
==============
|
|
|
|
.. class:: SnapToGrid(expression, *args, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_SnapToGrid.html>`__,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a geometry with all
|
|
points snapped to the given 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 both 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.
|
|
=================== =====================================================
|
|
|
|
``SymDifference``
|
|
=================
|
|
|
|
.. class:: SymDifference(expr1, expr2, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-symdifference>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_SymDifference.html>`__, Oracle,
|
|
SpatiaLite
|
|
|
|
Accepts two geographic fields or expressions and returns the geometric
|
|
symmetric difference (union without the intersection) between the given
|
|
parameters.
|
|
|
|
``Transform``
|
|
=============
|
|
|
|
.. class:: Transform(expression, srid, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Transform.html>`__,
|
|
Oracle, SpatiaLite
|
|
|
|
Accepts a geographic field or expression and a SRID integer code, and returns
|
|
the transformed geometry to the spatial reference system specified by the
|
|
``srid`` parameter.
|
|
|
|
.. 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.
|
|
|
|
``Translate``
|
|
=============
|
|
|
|
.. class:: Translate(expression, x, y, z=0.0, **extra)
|
|
|
|
*Availability*: `PostGIS <https://postgis.net/docs/ST_Translate.html>`__,
|
|
SpatiaLite
|
|
|
|
Accepts a single geographic field or expression and returns a geometry with
|
|
its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
|
|
parameters.
|
|
|
|
``Union``
|
|
=========
|
|
|
|
.. class:: Union(expr1, expr2, **extra)
|
|
|
|
*Availability*: `MySQL
|
|
<https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-union>`__,
|
|
`PostGIS <https://postgis.net/docs/ST_Union.html>`__, Oracle, SpatiaLite
|
|
|
|
Accepts two geographic fields or expressions and returns the union of both
|
|
geometries.
|