django1/docs/ref/contrib/gis/functions.txt

=============================
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:`BoundingCircle`   :class:`Difference`     :class:`ForceRHR`    :class:`AsGeoJSON`  :class:`IsValid`
:class:`Distance`   :class:`Centroid`         :class:`Intersection`   :class:`MakeValid`   :class:`AsGML`      :class:`MemSize`
:class:`Length`     :class:`Envelope`         :class:`SymDifference`  :class:`Reverse`     :class:`AsKML`      :class:`NumGeometries`
:class:`Perimeter`  :class:`PointOnSurface`   :class:`Union`          :class:`Scale`       :class:`AsSVG`      :class:`NumPoints`
..                                                                    :class:`SnapToGrid`  :class:`GeoHash`
..                                                                    :class:`Transform`
..                                                                    :class:`Translate`
==================  =======================   ======================  ===================  ==================  =====================

``Area``
========

.. class:: Area(expression, **extra)

*Availability*: MySQL, 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.

.. versionchanged:: 1.11

    In older versions, a raw value was returned on MySQL when used on
    projected SRS.

``AsGeoJSON``
=============

.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)

*Availability*: MySQL (≥ 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.
=====================  =====================================================

.. versionchanged:: 2.0

    MySQL support was added.

``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

.. versionchanged:: 1.11

    Oracle support was added.

``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.
=====================  =====================================================

__ http://www.w3.org/Graphics/SVG/

``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/GUID-82A61626-BB64-4793-B53D-A0DBEC91831A.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.

.. versionchanged:: 1.11

    Oracle support was added.

``Centroid``
============

.. class:: Centroid(expression, **extra)

*Availability*: MySQL, `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 (≥ 5.6.1), `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 (≥ 5.6.1), `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`.

.. versionchanged:: 1.11

    In older versions, a raw value was returned on MySQL when used on
    projected SRS.

``Envelope``
============

.. class:: Envelope(expression, **extra)

*Availability*: MySQL, `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.

``ForceRHR``
============

.. class:: ForceRHR(expression, **extra)

*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 (≥ 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.

.. versionchanged:: 2.0

    MySQL support was added.

__ https://en.wikipedia.org/wiki/Geohash

``Intersection``
================

.. class:: Intersection(expr1, expr2, **extra)

*Availability*: MySQL (≥ 5.6.1), `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 (≥ 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.

.. versionchanged:: 1.11

    SpatiaLite and Oracle support was added.

.. versionchanged:: 2.0

    MySQL support was added.

``Length``
==========

.. class:: Length(expression, spheroid=True, **extra)

*Availability*: MySQL, 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 an :class:`~django.contrib.gis.measure.Distance`
measure. On MySQL, a raw float value is returned when the coordinates
are geodetic.

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.

.. versionchanged:: 1.11

    In older versions, a raw value was returned on MySQL when used on
    projected SRS.

``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.

.. versionchanged:: 1.11

    SpatiaLite support was added.

``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, `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, `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.

.. versionchanged:: 1.11

    SpatiaLite support for non-``LINESTRING`` geometries was added.

``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 (≥ 5.6.1), `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 (≥ 5.6.1), `PostGIS
<https://postgis.net/docs/ST_Union.html>`__, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the union of both
geometries.