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: Fixed #36097 -- Replaced GIS functions table with section headers for better readability and navigation. --- docs/ref/contrib/gis/functions.txt | 812 +++++++++++++++++++------------------ 1 file changed, 409 insertions(+), 403 deletions(-) (limited to 'docs') 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,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 -`__, -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`` -========= +`__, +`PostGIS `__, 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 `__, 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 +`__ 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) - -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`` -========= + >>> 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 `__, 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://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 -`__, -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 +`__, +Oracle, `PostGIS `__, 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 -`__, -Oracle, `PostGIS `__, 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 `__, +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 +`__, +`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) + +*Availability*: `PostGIS `__, +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) @@ -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 -`__, -`PostGIS `__, Oracle, SpatiaLite +`__, +`PostGIS `__, 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 -`__ 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 +`__, +`PostGIS `__, 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 +`__, +`PostGIS `__, Oracle, SpatiaLite -.. class:: Envelope(expression, **extra) +Accepts two geographic fields or expressions and returns the union of both +geometries. -*Availability*: MariaDB, `MySQL -`__, -`Oracle `__, -`PostGIS `__, 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 -`__, -Oracle, `PostGIS `__, SpatiaLite +*Availability*: `PostGIS `__, +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 -`__, -Oracle, `PostGIS `__, SpatiaLite +*Availability*: `PostGIS `__, 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 -`__, -`PostGIS `__, 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 `__ -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 `__, SpatiaLite -*Availability*: `PostGIS `__ +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 `__, +SpatiaLite -*Availability*: MariaDB, `MySQL -`__, -`PostGIS `__, 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 `__ +*Availability*: `PostGIS `__, +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 -`__, -`PostGIS `__, 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 `__, +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 -`__, -Oracle, `PostGIS `__, 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 +`__, +Oracle, `PostGIS `__, 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 `__, -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 +`__, +Oracle, `PostGIS `__, 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 `__, -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 +`__, +Oracle, `PostGIS `__, SpatiaLite -``MemSize`` -=========== +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`. -.. class:: MemSize(expression, **extra) +Example: -*Availability*: `PostGIS `__ +.. 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 -`__, -`PostGIS `__, 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 `__, +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 -`__, -`PostGIS `__, 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) + -147.78711,70.245363 ... + -147.78711,70.245363 -``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 `__, -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 `__, SpatiaLite -*Availability*: `PostGIS `__, -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) + -103.04135,36.217596,0 ... + -103.04135,36.217596,0 -*Availability*: `PostGIS `__, 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 `__, SpatiaLite -*Availability*: `PostGIS `__ +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 `__, 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 +`__, +Oracle, `PostGIS `__, 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 `__, -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 -`__, -`PostGIS `__, Oracle, -SpatiaLite +`__, +Oracle, `PostGIS `__, 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 `__, -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 +`__, +`PostGIS `__, 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 `__, +.. 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 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 -`__, -`PostGIS `__, Oracle, SpatiaLite +`__, +`PostGIS `__, 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. -- cgit v1.3