mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-31 09:41:08 +00:00
Code Issues 32 Releases Wiki Activity

Fixed #36097 -- Replaced GIS functions table with section headers for better readability and navigation.

Browse Source
This commit is contained in:
Sarah Boyce
2025-03-19 13:16:32 +01:00
committed by GitHub
parent 08dae5bd46
commit ed1e7c02c9
1 changed files with 447 additions and 441 deletions
Download Patch File Download Diff File Expand all files Collapse all files

888
docs/ref/contrib/gis/functions.txt
View File

@@ -20,23 +20,11 @@ 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 Input format Output format Miscellaneous
========================= ======================== ====================== ======================= ================== ================== ======================
:class:`Area` :class:`Azimuth` :class:`Difference` :class:`ForcePolygonCW` :class:`AsGeoJSON` :class:`IsEmpty`
:class:`Distance` :class:`BoundingCircle` :class:`Intersection` :class:`MakeValid` :class:`AsGML` :class:`IsValid`
:class:`GeometryDistance` :class:`Centroid` :class:`SymDifference` :class:`Reverse` :class:`AsKML` :class:`MemSize`
:class:`Length` :class:`ClosestPoint` :class:`Union` :class:`Rotate` :class:`AsSVG` :class:`NumGeometries`
:class:`Perimeter` :class:`Envelope` :class:`Scale` :class:`FromWKB` :class:`AsWKB` :class:`NumPoints`
:class:`LineLocatePoint` :class:`SnapToGrid` :class:`FromWKT` :class:`AsWKT`
:class:`PointOnSurface` :class:`Transform` :class:`GeoHash`
:class:`Translate`
========================= ======================== ====================== ======================= ================== ================== ======================
Measurements
============
``Area``
========
--------
.. class:: Area(expression, **extra)
@@ -50,233 +38,8 @@ field as an :class:`~django.contrib.gis.measure.Area` measure.
MySQL and SpatiaLite without LWGEOM/RTTOPO don't support area calculations on
geographic SRSes.
``AsGeoJSON``
=============
.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-geojson-functions.html#function_st-asgeojson>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsGeoJSON.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `GeoJSON
<https://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:
.. code-block:: pycon
>>> 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. Ignored on
Oracle.
``crs`` Set this to ``True`` if you want the coordinate
reference system to be included in the returned
GeoJSON. Ignored on MySQL and Oracle.
``precision`` It may be used to specify the number of significant
digits for the coordinates in the GeoJSON
representation -- the default value is 8. Ignored on
Oracle.
===================== =====================================================
``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:
.. code-block:: pycon
>>> 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:
.. code-block:: pycon
>>> 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/
``AsWKB``
=========
.. class:: AsWKB(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-asbinary>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsBinary.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `Well-known
binary (WKB)`_ representation of the geometry.
Example:
.. code-block:: pycon
>>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'
``AsWKT``
=========
.. class:: AsWKT(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-astext>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsText.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `Well-known text
(WKT)`_ representation of the geometry.
Example:
.. code-block:: pycon
>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'
``Azimuth``
===========
.. class:: Azimuth(point_a, point_b, **extra)
*Availability*: `PostGIS <https://postgis.net/docs/ST_Azimuth.html>`__,
SpatiaLite (LWGEOM/RTTOPO)
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/en/database/oracle/oracle-database/21/spatl/
SDO_GEOM-reference.html#GUID-82A61626-BB64-4793-B53D-A0DBEC91831A>`_,
SpatiaLite 5.1+
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*: MariaDB, `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.
``ClosestPoint``
================
.. class:: ClosestPoint(expr1, expr2, **extra)
*Availability*: `PostGIS <https://postgis.net/docs/ST_ClosestPoint.html>`__,
SpatiaLite
Accepts two geographic fields or expressions and returns the 2-dimensional
point on geometry A that is closest to geometry B.
``Difference``
==============
.. class:: Difference(expr1, expr2, **extra)
*Availability*: MariaDB, `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)
@@ -324,79 +87,8 @@ queryset is calculated:
in kilometers. See :doc:`measure` for usage details and the list of
:ref:`supported_units`.
``Envelope``
============
.. class:: Envelope(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-general-property-functions.html#function_st-envelope>`__,
`Oracle <https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/
spatial-operators-reference.html#GUID-ACED800F-3435-44AA-9606-D40934A23ED0>`__,
`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.
``ForcePolygonCW``
==================
.. class:: ForcePolygonCW(expression, **extra)
*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.
``FromWKB``
===========
.. class:: FromWKB(expression, srid=0, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-wkb-functions.html#function_st-geomfromwkb>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_GeomFromWKB.html>`__, SpatiaLite
Creates geometry from `Well-known binary (WKB)`_ representation. The optional
``srid`` argument allows to specify the SRID of the resulting geometry.
``srid`` is ignored on Oracle.
``FromWKT``
===========
.. class:: FromWKT(expression, srid=0, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-wkt-functions.html#function_st-geomfromtext>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_GeomFromText.html>`__, SpatiaLite
Creates geometry from `Well-known text (WKT)`_ representation. The optional
``srid`` argument allows to specify the SRID of the resulting geometry.
``srid`` is ignored on Oracle.
``GeoHash``
===========
.. class:: GeoHash(expression, precision=None, **extra)
*Availability*: `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-geohash-functions.html#function_st-geohash>`__,
`PostGIS <https://postgis.net/docs/ST_GeoHash.html>`__, SpatiaLite
(LWGEOM/RTTOPO)
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
``GeometryDistance``
====================
--------------------
.. class:: GeometryDistance(expr1, expr2, **extra)
@@ -406,42 +98,8 @@ Accepts two geographic fields or expressions and returns the distance between
them. When used in an :meth:`~django.db.models.query.QuerySet.order_by` clause,
it provides index-assisted nearest-neighbor result sets.
``Intersection``
================
.. class:: Intersection(expr1, expr2, **extra)
*Availability*: MariaDB, `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.
``IsEmpty``
===========
.. class:: IsEmpty(expr)
*Availability*: `PostGIS <https://postgis.net/docs/ST_IsEmpty.html>`__
Accepts a geographic field or expression and tests if the value is an empty
geometry. Returns ``True`` if its value is empty and ``False`` otherwise.
``IsValid``
===========
.. class:: IsValid(expr)
*Availability*: `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-convenience-functions.html#function_st-isvalid>`__,
`PostGIS <https://postgis.net/docs/ST_IsValid.html>`__, Oracle, SpatiaLite
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)
@@ -460,8 +118,87 @@ resource-intensive) with the ``spheroid`` keyword argument.
MySQL doesn't support length calculations on geographic SRSes.
``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.
Relationships
=============
``Azimuth``
-----------
.. class:: Azimuth(point_a, point_b, **extra)
*Availability*: `PostGIS <https://postgis.net/docs/ST_Azimuth.html>`__,
SpatiaLite (LWGEOM/RTTOPO)
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/en/database/oracle/oracle-database/21/spatl/
SDO_GEOM-reference.html#GUID-82A61626-BB64-4793-B53D-A0DBEC91831A>`_,
SpatiaLite 5.1+
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*: MariaDB, `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.
``ClosestPoint``
----------------
.. class:: ClosestPoint(expr1, expr2, **extra)
*Availability*: `PostGIS <https://postgis.net/docs/ST_ClosestPoint.html>`__,
SpatiaLite
Accepts two geographic fields or expressions and returns the 2-dimensional
point on geometry A that is closest to geometry B.
``Envelope``
------------
.. class:: Envelope(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-general-property-functions.html#function_st-envelope>`__,
`Oracle <https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/
spatial-operators-reference.html#GUID-ACED800F-3435-44AA-9606-D40934A23ED0>`__,
`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.
``LineLocatePoint``
===================
-------------------
.. class:: LineLocatePoint(linestring, point, **extra)
@@ -471,8 +208,92 @@ 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.
``PointOnSurface``
------------------
.. class:: PointOnSurface(expression, **extra)
*Availability*: `PostGIS <https://postgis.net/docs/ST_PointOnSurface.html>`__,
MariaDB, 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``.
Operations
==========
``Difference``
--------------
.. class:: Difference(expr1, expr2, **extra)
*Availability*: MariaDB, `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.
``Intersection``
----------------
.. class:: Intersection(expr1, expr2, **extra)
*Availability*: MariaDB, `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.
``SymDifference``
-----------------
.. class:: SymDifference(expr1, expr2, **extra)
*Availability*: MariaDB, `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.
``Union``
---------
.. class:: Union(expr1, expr2, **extra)
*Availability*: MariaDB, `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.
.. _`Well-known binary (WKB)`: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
.. _`Well-known text (WKT)`: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry
Editors
=======
``ForcePolygonCW``
------------------
.. class:: ForcePolygonCW(expression, **extra)
*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.
``MakeValid``
=============
-------------
.. class:: MakeValid(expr)
@@ -484,70 +305,8 @@ 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*: MariaDB, `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*: MariaDB, `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>`__,
MariaDB, 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)
@@ -558,7 +317,7 @@ Accepts a single geographic field or expression and returns a geometry with
reversed coordinates.
``Rotate``
==========
----------
.. versionadded:: 6.0
@@ -571,7 +330,7 @@ rotation can be performed around a point, defined by the ``origin``
parameter.
``Scale``
=========
---------
.. class:: Scale(expression, x, y, z=0.0, **extra)
@@ -582,7 +341,7 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally
``z`` parameters.
``SnapToGrid``
==============
--------------
.. class:: SnapToGrid(expression, *args, **extra)
@@ -602,22 +361,8 @@ Number of Arguments Description
4 X, Y sizes and the corresponding X, Y origins.
=================== =====================================================
``SymDifference``
=================
.. class:: SymDifference(expr1, expr2, **extra)
*Availability*: MariaDB, `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)
@@ -635,7 +380,7 @@ the transformed geometry to the spatial reference system specified by the
are not necessarily the same as those used by PostGIS.
``Translate``
=============
-------------
.. class:: Translate(expression, x, y, z=0.0, **extra)
@@ -646,17 +391,278 @@ 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``
=========
Input format
============
.. class:: Union(expr1, expr2, **extra)
``FromWKB``
-----------
.. class:: FromWKB(expression, srid=0, **extra)
*Availability*: MariaDB, `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
<https://dev.mysql.com/doc/refman/en/gis-wkb-functions.html#function_st-geomfromwkb>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_GeomFromWKB.html>`__, SpatiaLite
Accepts two geographic fields or expressions and returns the union of both
geometries.
Creates geometry from `Well-known binary (WKB)`_ representation. The optional
``srid`` argument allows to specify the SRID of the resulting geometry.
``srid`` is ignored on Oracle.
.. _`Well-known binary (WKB)`: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary
.. _`Well-known text (WKT)`: https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry
``FromWKT``
-----------
.. class:: FromWKT(expression, srid=0, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-wkt-functions.html#function_st-geomfromtext>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_GeomFromText.html>`__, SpatiaLite
Creates geometry from `Well-known text (WKT)`_ representation. The optional
``srid`` argument allows to specify the SRID of the resulting geometry.
``srid`` is ignored on Oracle.
Output format
=============
``AsGeoJSON``
-------------
.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-geojson-functions.html#function_st-asgeojson>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsGeoJSON.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `GeoJSON
<https://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:
.. code-block:: pycon
>>> 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. Ignored on
Oracle.
``crs`` Set this to ``True`` if you want the coordinate
reference system to be included in the returned
GeoJSON. Ignored on MySQL and Oracle.
``precision`` It may be used to specify the number of significant
digits for the coordinates in the GeoJSON
representation -- the default value is 8. Ignored on
Oracle.
===================== =====================================================
``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:
.. code-block:: pycon
>>> 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:
.. code-block:: pycon
>>> 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/
``AsWKB``
---------
.. class:: AsWKB(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-asbinary>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsBinary.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `Well-known
binary (WKB)`_ representation of the geometry.
Example:
.. code-block:: pycon
>>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'
``AsWKT``
---------
.. class:: AsWKT(expression, **extra)
*Availability*: MariaDB, `MySQL
<https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-astext>`__,
Oracle, `PostGIS <https://postgis.net/docs/ST_AsText.html>`__, SpatiaLite
Accepts a single geographic field or expression and returns a `Well-known text
(WKT)`_ representation of the geometry.
Example:
.. code-block:: pycon
>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'
``GeoHash``
-----------
.. class:: GeoHash(expression, precision=None, **extra)
*Availability*: `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-geohash-functions.html#function_st-geohash>`__,
`PostGIS <https://postgis.net/docs/ST_GeoHash.html>`__, SpatiaLite
(LWGEOM/RTTOPO)
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
Miscellaneous
=============
``IsEmpty``
-----------
.. class:: IsEmpty(expr)
*Availability*: `PostGIS <https://postgis.net/docs/ST_IsEmpty.html>`__
Accepts a geographic field or expression and tests if the value is an empty
geometry. Returns ``True`` if its value is empty and ``False`` otherwise.
``IsValid``
-----------
.. class:: IsValid(expr)
*Availability*: `MySQL
<https://dev.mysql.com/doc/refman/en/spatial-convenience-functions.html#function_st-isvalid>`__,
`PostGIS <https://postgis.net/docs/ST_IsValid.html>`__, Oracle, SpatiaLite
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.
``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*: MariaDB, `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*: MariaDB, `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.