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

docs/ref/contrib/gis/functions.txt

@@ -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,169 +38,102 @@ 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``
-=============
+``Distance``
+------------
 
-.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
+.. class:: Distance(expr1, expr2, spheroid=None, **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``
-=========
+<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
 
-.. class:: AsKML(expression, precision=8, **extra)
+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.
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_AsKML.html>`__, SpatiaLite
+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).
 
-Accepts a single geographic field or expression and returns a `Keyhole Markup
-Language (KML)`__ representation of the geometry.
+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).
 
-Example:
+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:
 
 .. 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``
-=========
+    >>> 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
+    ...
 
-.. class:: AsSVG(expression, relative=False, precision=8, **extra)
+.. note::
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_AsSVG.html>`__, SpatiaLite
+    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`.
 
-Accepts a single geographic field or expression and returns a `Scalable Vector
-Graphics (SVG)`__ representation of the geometry.
+``GeometryDistance``
+--------------------
 
-=====================  =====================================================
-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.
+.. class:: GeometryDistance(expr1, expr2, **extra)
 
-``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.
-=====================  =====================================================
+*Availability*: `PostGIS <https://postgis.net/docs/geometry_distance_knn.html>`__
 
-__ https://www.w3.org/Graphics/SVG/
+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.
 
-``AsWKB``
-=========
+``Length``
+----------
 
-.. class:: AsWKB(expression, **extra)
+.. class:: Length(expression, spheroid=True, **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
+<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
 
-    >>> 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@'
+Accepts a single geographic linestring or multilinestring field or expression
+and returns its length as a :class:`~django.contrib.gis.measure.Distance`
+measure.
 
-``AsWKT``
-=========
+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.
 
-.. class:: AsWKT(expression, **extra)
+MySQL doesn't support length calculations on geographic SRSes.
 
-*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
+``Perimeter``
+-------------
 
-Accepts a single geographic field or expression and returns a `Well-known text
-(WKT)`_ representation of the geometry.
+.. class:: Perimeter(expression, **extra)
 
-Example:
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Perimeter.html>`__,
+Oracle, SpatiaLite
 
-.. code-block:: pycon
+Accepts a single geographic field or expression and returns the perimeter of the
+geometry field as a :class:`~django.contrib.gis.measure.Distance` object.
 
-    >>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
-    'POINT (55.137555 61.451728)'
+Relationships
+=============
 
 ``Azimuth``
-===========
+-----------
 
 .. class:: Azimuth(point_a, point_b, **extra)
 
@@ -225,7 +146,7 @@ referenced from north and is positive clockwise: north = ``0``; east = ``π/2``;
 south = ``π``; west = ``3π/2``.
 
 ``BoundingCircle``
-==================
+------------------
 
 .. class:: BoundingCircle(expression, num_seg=48, **extra)
 
@@ -240,7 +161,7 @@ polygon that can fully contain the geometry.
 The ``num_seg`` parameter is used only on PostGIS.
 
 ``Centroid``
-============
+------------
 
 .. class:: Centroid(expression, **extra)
 
@@ -252,7 +173,7 @@ Accepts a single geographic field or expression and returns the ``centroid``
 value of the geometry.
 
 ``ClosestPoint``
-================
+----------------
 
 .. class:: ClosestPoint(expr1, expr2, **extra)
 
@@ -262,8 +183,47 @@ 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)
+
+*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.
+
+``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)
 
@@ -275,71 +235,52 @@ 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``
-============
+``Intersection``
+----------------
 
-.. class:: Distance(expr1, expr2, spheroid=None, **extra)
+.. class:: Intersection(expr1, expr2, **extra)
 
 *Availability*: MariaDB, `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
+<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 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.
+Accepts two geographic fields or expressions and returns the geometric
+intersection between them.
 
-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).
+``SymDifference``
+-----------------
 
-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).
+.. class:: SymDifference(expr1, expr2, **extra)
 
-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:
+*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
 
-.. code-block:: pycon
-
-    >>> 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
-    ...
+Accepts two geographic fields or expressions and returns the geometric
+symmetric difference (union without the intersection) between the given
+parameters.
 
-.. note::
+``Union``
+---------
 
-    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`.
+.. class:: Union(expr1, expr2, **extra)
 
-``Envelope``
-============
+*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
 
-.. class:: Envelope(expression, **extra)
+Accepts two geographic fields or expressions and returns the union of both
+geometries.
 
-*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
+.. _`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
 
-Accepts a single geographic field or expression and returns the geometry
-representing the bounding box of the geometry.
+Editors
+=======
 
 ``ForcePolygonCW``
-==================
+------------------
 
 .. class:: ForcePolygonCW(expression, **extra)
 
@@ -351,312 +292,377 @@ 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``
-===========
+``MakeValid``
+-------------
 
-.. class:: FromWKB(expression, srid=0, **extra)
+.. class:: MakeValid(expr)
 
-*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
+*Availability*: `PostGIS <https://postgis.net/docs/ST_MakeValid.html>`__,
+SpatiaLite (LWGEOM/RTTOPO)
 
-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.
+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.
 
-``FromWKT``
-===========
+``Reverse``
+-----------
 
-.. class:: FromWKT(expression, srid=0, **extra)
+.. class:: Reverse(expression, **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
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Reverse.html>`__, Oracle,
+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.
+Accepts a single geographic field or expression and returns a geometry with
+reversed coordinates.
 
-``GeoHash``
-===========
+``Rotate``
+----------
 
-.. class:: GeoHash(expression, precision=None, **extra)
+.. versionadded:: 6.0
 
-*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)
+.. class:: Rotate(expression, angle, origin=None, **extra)
 
-Accepts a single geographic field or expression and returns a `GeoHash`__
-representation of the geometry.
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Rotate.html>`__
 
-The ``precision`` keyword argument controls the number of characters in the
-result.
+Rotates a geometry by a specified ``angle`` around the origin. Optionally, the
+rotation can be performed around a point, defined by the ``origin``
+parameter.
 
-__ https://en.wikipedia.org/wiki/Geohash
+``Scale``
+---------
 
-``GeometryDistance``
-====================
+.. class:: Scale(expression, x, y, z=0.0, **extra)
 
-.. class:: GeometryDistance(expr1, expr2, **extra)
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Scale.html>`__, SpatiaLite
 
-*Availability*: `PostGIS <https://postgis.net/docs/geometry_distance_knn.html>`__
+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.
 
-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.
+``SnapToGrid``
+--------------
 
-``Intersection``
-================
+.. class:: SnapToGrid(expression, *args, **extra)
 
-.. class:: Intersection(expr1, expr2, **extra)
+*Availability*: `PostGIS <https://postgis.net/docs/ST_SnapToGrid.html>`__,
+SpatiaLite
 
-*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 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.
 
-Accepts two geographic fields or expressions and returns the geometric
-intersection between them.
+===================  =====================================================
+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.
+===================  =====================================================
 
-``IsEmpty``
-===========
+``Transform``
+-------------
 
-.. class:: IsEmpty(expr)
+.. class:: Transform(expression, srid, **extra)
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_IsEmpty.html>`__
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Transform.html>`__,
+Oracle, SpatiaLite
 
-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.
+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.
 
-``IsValid``
-===========
+.. note::
 
-.. class:: IsValid(expr)
+    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.
 
-*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
+``Translate``
+-------------
 
-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.
+.. class:: Translate(expression, x, y, z=0.0, **extra)
 
-``Length``
-==========
+*Availability*: `PostGIS <https://postgis.net/docs/ST_Translate.html>`__,
+SpatiaLite
 
-.. class:: Length(expression, spheroid=True, **extra)
+Accepts a single geographic field or expression and returns a geometry with
+its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
+parameters.
 
-*Availability*: MariaDB, `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
+Input format
+============
 
-Accepts a single geographic linestring or multilinestring field or expression
-and returns its length as a :class:`~django.contrib.gis.measure.Distance`
-measure.
+``FromWKB``
+-----------
 
-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.
+.. class:: FromWKB(expression, srid=0, **extra)
 
-MySQL doesn't support length calculations on geographic SRSes.
+*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
 
-``LineLocatePoint``
-===================
+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.
 
-.. class:: LineLocatePoint(linestring, point, **extra)
+``FromWKT``
+-----------
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_LineLocatePoint.html>`__,
-SpatiaLite
+.. class:: FromWKT(expression, srid=0, **extra)
 
-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.
+*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
 
-``MakeValid``
+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
 =============
 
-.. class:: MakeValid(expr)
+``AsGeoJSON``
+-------------
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_MakeValid.html>`__,
-SpatiaLite (LWGEOM/RTTOPO)
+.. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)
 
-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.
+*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
 
-``MemSize``
-===========
+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`.
 
-.. class:: MemSize(expression, **extra)
+Example:
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_MemSize.html>`__
+.. code-block:: pycon
 
-Accepts a single geographic field or expression and returns the memory size
-(number of bytes) that the geometry field takes.
+    >>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
+    {"type":"Point","coordinates":[-87.65018,41.85039]}
 
-``NumGeometries``
-=================
+=====================  =====================================================
+Keyword Argument       Description
+=====================  =====================================================
+``bbox``               Set this to ``True`` if you want the bounding box
+                       to be included in the returned GeoJSON. Ignored on
+                       Oracle.
 
-.. class:: NumGeometries(expression, **extra)
+``crs``                Set this to ``True`` if you want the coordinate
+                       reference system to be included in the returned
+                       GeoJSON. Ignored on MySQL and Oracle.
 
-*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
+``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.
+=====================  =====================================================
 
-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.
+``AsGML``
+---------
 
-On MySQL, returns ``None`` for single geometries.
+.. class:: AsGML(expression, version=2, precision=8, **extra)
 
-``NumPoints``
-=============
+*Availability*: Oracle, `PostGIS <https://postgis.net/docs/ST_AsGML.html>`__,
+SpatiaLite
 
-.. class:: NumPoints(expression, **extra)
+Accepts a single geographic field or expression and returns a `Geographic Markup
+Language (GML)`__ representation of the geometry.
 
-*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
+Example:
 
-Accepts a single geographic field or expression and returns the number of points
-in a geometry.
+.. code-block:: pycon
 
-On MySQL, returns ``None`` for any non-``LINESTRING`` geometry.
+    >>> 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>
 
-``Perimeter``
-=============
+=====================  =====================================================
+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.
 
-.. class:: Perimeter(expression, **extra)
+``version``            Specifies the GML version to use: 2 (default) or 3.
+=====================  =====================================================
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Perimeter.html>`__,
-Oracle, SpatiaLite
+__ https://en.wikipedia.org/wiki/Geography_Markup_Language
 
-Accepts a single geographic field or expression and returns the perimeter of the
-geometry field as a :class:`~django.contrib.gis.measure.Distance` object.
+``AsKML``
+---------
 
-``PointOnSurface``
-==================
+.. class:: AsKML(expression, precision=8, **extra)
 
-.. class:: PointOnSurface(expression, **extra)
+*Availability*: `PostGIS <https://postgis.net/docs/ST_AsKML.html>`__, SpatiaLite
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_PointOnSurface.html>`__,
-MariaDB, Oracle, SpatiaLite
+Accepts a single geographic field or expression and returns a `Keyhole Markup
+Language (KML)`__ representation of the geometry.
 
-Accepts a single geographic field or expression and returns a ``Point`` geometry
-guaranteed to lie on the surface of the field; otherwise returns ``None``.
+Example:
 
-``Reverse``
-===========
+.. code-block:: pycon
 
-.. class:: Reverse(expression, **extra)
+    >>> 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>
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Reverse.html>`__, Oracle,
-SpatiaLite
+=====================  =====================================================
+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.
+=====================  =====================================================
 
-Accepts a single geographic field or expression and returns a geometry with
-reversed coordinates.
+__ https://developers.google.com/kml/documentation/
 
-``Rotate``
-==========
+``AsSVG``
+---------
 
-.. versionadded:: 6.0
+.. class:: AsSVG(expression, relative=False, precision=8, **extra)
 
-.. class:: Rotate(expression, angle, origin=None, **extra)
+*Availability*: `PostGIS <https://postgis.net/docs/ST_AsSVG.html>`__, SpatiaLite
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Rotate.html>`__
+Accepts a single geographic field or expression and returns a `Scalable Vector
+Graphics (SVG)`__ representation of the geometry.
 
-Rotates a geometry by a specified ``angle`` around the origin. Optionally, the
-rotation can be performed around a point, defined by the ``origin``
-parameter.
+=====================  =====================================================
+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.
 
-``Scale``
-=========
+``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.
+=====================  =====================================================
 
-.. class:: Scale(expression, x, y, z=0.0, **extra)
+__ https://www.w3.org/Graphics/SVG/
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Scale.html>`__, SpatiaLite
+``AsWKB``
+---------
 
-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.
+.. class:: AsWKB(expression, **extra)
 
-``SnapToGrid``
-==============
+*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
 
-.. class:: SnapToGrid(expression, *args, **extra)
+Accepts a single geographic field or expression and returns a `Well-known
+binary (WKB)`_ representation of the geometry.
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_SnapToGrid.html>`__,
-SpatiaLite
+Example:
 
-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.
+.. code-block:: pycon
 
-===================  =====================================================
-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.
-===================  =====================================================
+    >>> 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@'
 
-``SymDifference``
-=================
+``AsWKT``
+---------
 
-.. class:: SymDifference(expr1, expr2, **extra)
+.. class:: AsWKT(expression, **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
+<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 two geographic fields or expressions and returns the geometric
-symmetric difference (union without the intersection) between the given
-parameters.
+Accepts a single geographic field or expression and returns a `Well-known text
+(WKT)`_ representation of the geometry.
 
-``Transform``
-=============
+Example:
 
-.. class:: Transform(expression, srid, **extra)
+.. code-block:: pycon
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Transform.html>`__,
-Oracle, SpatiaLite
+    >>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
+    'POINT (55.137555 61.451728)'
 
-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.
+``GeoHash``
+-----------
 
-.. note::
+.. class:: GeoHash(expression, precision=None, **extra)
 
-    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.
+*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)
 
-``Translate``
+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
 =============
 
-.. class:: Translate(expression, x, y, z=0.0, **extra)
+``IsEmpty``
+-----------
 
-*Availability*: `PostGIS <https://postgis.net/docs/ST_Translate.html>`__,
+.. 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 a geometry with
-its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric
-parameters.
+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.
 
-``Union``
-=========
+On MySQL, returns ``None`` for single geometries.
 
-.. class:: Union(expr1, expr2, **extra)
+``NumPoints``
+-------------
+
+.. class:: NumPoints(expression, **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-linestring-property-functions.html#function_st-numpoints>`__,
+`PostGIS <https://postgis.net/docs/ST_NPoints.html>`__, Oracle, SpatiaLite
 
-Accepts two geographic fields or expressions and returns the union of both
-geometries.
+Accepts a single geographic field or expression and returns the number of points
+in a geometry.
 
-.. _`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
+On MySQL, returns ``None`` for any non-``LINESTRING`` geometry.