From ed1e7c02c9db2cc28b3ab5621ce6315fcee54b27 Mon Sep 17 00:00:00 2001 From: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com> Date: Wed, 19 Mar 2025 13:16:32 +0100 Subject: [PATCH] Fixed #36097 -- Replaced GIS functions table with section headers for better readability and navigation. --- docs/ref/contrib/gis/functions.txt | 888 +++++++++++++++-------------- 1 file changed, 447 insertions(+), 441 deletions(-) diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 4e1ae167b8..3133e89b59 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/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,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 -`__, -Oracle, `PostGIS `__, SpatiaLite - -Accepts a single geographic field or expression and returns a `GeoJSON -`_ 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 `__, -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) - -147.78711,70.245363 ... - -147.78711,70.245363 - -===================== ===================================================== -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 `__, 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) - -103.04135,36.217596,0 ... - -103.04135,36.217596,0 - -===================== ===================================================== -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 `__, 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 -`__, -Oracle, `PostGIS `__, 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 -`__, -Oracle, `PostGIS `__, 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 `__, -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 `__, -`Oracle `_, -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 -`__, -`PostGIS `__, 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 `__, -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 -`__, -`PostGIS `__, 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 -`__, -`Oracle `__, -`PostGIS `__, 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 `__, -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 -`__, -Oracle, `PostGIS `__, 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 -`__, -Oracle, `PostGIS `__, 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 -`__, -`PostGIS `__, 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 -`__, -`PostGIS `__, Oracle, SpatiaLite - -Accepts two geographic fields or expressions and returns the geometric -intersection between them. - -``IsEmpty`` -=========== - -.. class:: IsEmpty(expr) - -*Availability*: `PostGIS `__ - -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 -`__, -`PostGIS `__, 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 `__, +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 `__, +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 `__, +`Oracle `_, +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 +`__, +`PostGIS `__, 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 `__, +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 +`__, +`Oracle `__, +`PostGIS `__, 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 `__, +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 +`__, +`PostGIS `__, 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 +`__, +`PostGIS `__, Oracle, SpatiaLite + +Accepts two geographic fields or expressions and returns the geometric +intersection between them. + +``SymDifference`` +----------------- + +.. class:: SymDifference(expr1, expr2, **extra) + +*Availability*: MariaDB, `MySQL +`__, +`PostGIS `__, 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 +`__, +`PostGIS `__, 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 `__, +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 `__ - -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 -`__, -`PostGIS `__, 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 -`__, -`PostGIS `__, 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 `__, -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 `__, -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 -`__, -`PostGIS `__, 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 -`__, -`PostGIS `__, Oracle, SpatiaLite +`__, +Oracle, `PostGIS `__, 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 +`__, +Oracle, `PostGIS `__, 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 +`__, +Oracle, `PostGIS `__, SpatiaLite + +Accepts a single geographic field or expression and returns a `GeoJSON +`_ 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 `__, +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) + -147.78711,70.245363 ... + -147.78711,70.245363 + +===================== ===================================================== +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 `__, 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) + -103.04135,36.217596,0 ... + -103.04135,36.217596,0 + +===================== ===================================================== +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 `__, 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 +`__, +Oracle, `PostGIS `__, 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 +`__, +Oracle, `PostGIS `__, 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 +`__, +`PostGIS `__, 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 `__ + +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 +`__, +`PostGIS `__, 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 `__ + +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 +`__, +`PostGIS `__, 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 +`__, +`PostGIS `__, 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.