From 8d5bccfe762047cc550788708322d0872a9038d4 Mon Sep 17 00:00:00 2001 From: Sergey Fedoseev <fedoseev.sergey@gmail.com> Date: Thu, 16 Mar 2017 23:47:51 +0500 Subject: [PATCH] [1.11.x] Linked GIS functions docs to corresponding PostGIS docs. Backport of 1c3ddc0d27f1fa2ad35168beba52fb19a569278c from master --- docs/ref/contrib/gis/functions.txt | 77 +++++++++++++++++++----------- 1 file changed, 50 insertions(+), 27 deletions(-) diff --git a/docs/ref/contrib/gis/functions.txt b/docs/ref/contrib/gis/functions.txt index 43a417e7aa..4a6d6abe6a 100644 --- a/docs/ref/contrib/gis/functions.txt +++ b/docs/ref/contrib/gis/functions.txt @@ -37,7 +37,8 @@ Measurement Relationships Operations Editors .. class:: Area(expression, **extra) -*Availability*: MySQL, Oracle, PostGIS, SpatiaLite +*Availability*: MySQL, Oracle, +`PostGIS <https://postgis.net/docs/ST_Area.html>`__, SpatiaLite Accepts a single geographic field or expression and returns the area of the field as an :class:`~django.contrib.gis.measure.Area` measure. On MySQL, a raw @@ -53,7 +54,8 @@ float value is returned when the coordinates are geodetic. .. class:: AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_AsGeoJSON.html>`__, +SpatiaLite Accepts a single geographic field or expression and returns a `GeoJSON <http://geojson.org/>`_ representation of the geometry. Note that the result is @@ -85,7 +87,8 @@ Keyword Argument Description .. class:: AsGML(expression, version=2, precision=8, **extra) -*Availability*: Oracle, PostGIS, SpatiaLite +*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. @@ -118,7 +121,7 @@ __ https://en.wikipedia.org/wiki/Geography_Markup_Language .. class:: AsKML(expression, precision=8, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_AsKML.html>`__, SpatiaLite Accepts a single geographic field or expression and returns a `Keyhole Markup Language (KML)`__ representation of the geometry. @@ -145,7 +148,7 @@ __ https://developers.google.com/kml/documentation/ .. class:: AsSVG(expression, relative=False, precision=8, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_AsSVG.html>`__, SpatiaLite Accepts a single geographic field or expression and returns a `Scalable Vector Graphics (SVG)`__ representation of the geometry. @@ -186,7 +189,8 @@ The ``num_seg`` parameter is used only on PostGIS. .. class:: Centroid(expression, **extra) -*Availability*: MySQL, PostGIS, Oracle, SpatiaLite +*Availability*: MySQL, `PostGIS <https://postgis.net/docs/ST_Centroid.html>`__, +Oracle, SpatiaLite Accepts a single geographic field or expression and returns the ``centroid`` value of the geometry. @@ -196,7 +200,8 @@ value of the geometry. .. class:: Difference(expr1, expr2, **extra) -*Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite +*Availability*: MySQL (≥ 5.6.1), `PostGIS +<https://postgis.net/docs/ST_Difference.html>`__, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric difference, that is the part of geometry A that does not intersect with @@ -211,7 +216,8 @@ geometry B. .. class:: Distance(expr1, expr2, spheroid=None, **extra) -*Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite +*Availability*: MySQL (≥ 5.6.1), `PostGIS +<https://postgis.net/docs/ST_Distance.html>`__, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the distance between them, as a :class:`~django.contrib.gis.measure.Distance` object. On MySQL, a raw @@ -219,7 +225,8 @@ float value is returned when the coordinates are geodetic. On backends that support distance calculation on geodetic coordinates, the proper backend function is automatically chosen depending on the SRID value of -the geometries (e.g. ``ST_Distance_Sphere`` on PostGIS). +the geometries (e.g. `ST_DistanceSphere +<https://postgis.net/docs/ST_DistanceSphere.html>`__ on PostGIS). When distances are calculated with geodetic (angular) coordinates, as is the case with the default WGS84 (4326) SRID, you can set the ``spheroid`` keyword @@ -259,7 +266,8 @@ queryset is calculated:: .. class:: Envelope(expression, **extra) -*Availability*: MySQL, PostGIS, SpatiaLite +*Availability*: MySQL, `PostGIS <https://postgis.net/docs/ST_Envelope.html>`__, +SpatiaLite Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry. @@ -280,7 +288,8 @@ right-hand rule. .. class:: GeoHash(expression, precision=None, **extra) -*Availability*: PostGIS, SpatiaLite (LWGEOM) +*Availability*: `PostGIS <https://postgis.net/docs/ST_GeoHash.html>`__, +SpatiaLite (LWGEOM) Accepts a single geographic field or expression and returns a `GeoHash`__ representation of the geometry. @@ -299,7 +308,8 @@ __ https://en.wikipedia.org/wiki/Geohash .. class:: Intersection(expr1, expr2, **extra) -*Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite +*Availability*: MySQL (≥ 5.6.1), `PostGIS +<https://postgis.net/docs/ST_Intersection.html>`__, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric intersection between them. @@ -315,7 +325,8 @@ intersection between them. .. versionadded:: 1.10 -*Availability*: PostGIS, Oracle, SpatiaLite (LWGEOM) +*Availability*: `PostGIS <https://postgis.net/docs/ST_IsValid.html>`__, +Oracle, SpatiaLite (LWGEOM) Accepts a geographic field or expression and tests if the value is well formed. Returns ``True`` if its value is a valid geometry and ``False`` otherwise. @@ -329,7 +340,8 @@ Returns ``True`` if its value is a valid geometry and ``False`` otherwise. .. class:: Length(expression, spheroid=True, **extra) -*Availability*: MySQL, Oracle, PostGIS, SpatiaLite +*Availability*: MySQL, Oracle, `PostGIS +<https://postgis.net/docs/ST_Length.html>`__, SpatiaLite Accepts a single geographic linestring or multilinestring field or expression and returns its length as an :class:`~django.contrib.gis.measure.Distance` @@ -353,7 +365,8 @@ resource-intensive) with the ``spheroid`` keyword argument. .. versionadded:: 1.10 -*Availability*: PostGIS, SpatiaLite (LWGEOM) +*Availability*: `PostGIS <https://postgis.net/docs/ST_MakeValid.html>`__, +SpatiaLite (LWGEOM) Accepts a geographic field or expression and attempts to convert the value into a valid geometry without losing any of the input vertices. Geometries that are @@ -369,7 +382,7 @@ multipolygon and the result might be of lower dimension than the input. .. class:: MemSize(expression, **extra) -*Availability*: PostGIS +*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. @@ -379,7 +392,8 @@ Accepts a single geographic field or expression and returns the memory size .. class:: NumGeometries(expression, **extra) -*Availability*: MySQL, PostGIS, Oracle, SpatiaLite +*Availability*: MySQL, `PostGIS +<https://postgis.net/docs/ST_NumGeometries.html>`__, Oracle, SpatiaLite Accepts a single geographic field or expression and returns the number of geometries if the geometry field is a collection (e.g., a ``GEOMETRYCOLLECTION`` @@ -390,7 +404,8 @@ or ``MULTI*`` field); otherwise returns ``None``. .. class:: NumPoints(expression, **extra) -*Availability*: MySQL, PostGIS, Oracle, SpatiaLite +*Availability*: MySQL, `PostGIS <https://postgis.net/docs/ST_NPoints.html>`__, +Oracle, SpatiaLite Accepts a single geographic field or expression and returns the number of points in the first linestring in the geometry field; otherwise returns ``None``. @@ -400,7 +415,8 @@ in the first linestring in the geometry field; otherwise returns ``None``. .. class:: Perimeter(expression, **extra) -*Availability*: PostGIS, Oracle, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_Perimeter.html>`__, +Oracle, SpatiaLite Accepts a single geographic field or expression and returns the perimeter of the geometry field as a :class:`~django.contrib.gis.measure.Distance` object. On @@ -412,7 +428,8 @@ determine the unit of the field. .. class:: PointOnSurface(expression, **extra) -*Availability*: PostGIS, Oracle, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_PointOnSurface.html>`__, +Oracle, SpatiaLite Accepts a single geographic field or expression and returns a ``Point`` geometry guaranteed to lie on the surface of the field; otherwise returns ``None``. @@ -422,7 +439,8 @@ guaranteed to lie on the surface of the field; otherwise returns ``None``. .. class:: Reverse(expression, **extra) -*Availability*: PostGIS, Oracle, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_Reverse.html>`__, Oracle, +SpatiaLite Accepts a single geographic field or expression and returns a geometry with reversed coordinates. @@ -432,7 +450,7 @@ reversed coordinates. .. class:: Scale(expression, x, y, z=0.0, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_Scale.html>`__, SpatiaLite Accepts a single geographic field or expression and returns a geometry with scaled coordinates by multiplying them with the ``x``, ``y``, and optionally @@ -443,7 +461,8 @@ scaled coordinates by multiplying them with the ``x``, ``y``, and optionally .. class:: SnapToGrid(expression, *args, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_SnapToGrid.html>`__, +SpatiaLite Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid @@ -463,7 +482,8 @@ Number of Arguments Description .. class:: SymDifference(expr1, expr2, **extra) -*Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite +*Availability*: MySQL (≥ 5.6.1), `PostGIS +<https://postgis.net/docs/ST_SymDifference.html>`__, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given @@ -478,7 +498,8 @@ parameters. .. class:: Transform(expression, srid, **extra) -*Availability*: PostGIS, Oracle, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_Transform.html>`__, +Oracle, SpatiaLite Accepts a geographic field or expression and a SRID integer code, and returns the transformed geometry to the spatial reference system specified by the @@ -495,7 +516,8 @@ the transformed geometry to the spatial reference system specified by the .. class:: Translate(expression, x, y, z=0.0, **extra) -*Availability*: PostGIS, SpatiaLite +*Availability*: `PostGIS <https://postgis.net/docs/ST_Translate.html>`__, +SpatiaLite Accepts a single geographic field or expression and returns a geometry with its coordinates offset by the ``x``, ``y``, and optionally ``z`` numeric @@ -506,7 +528,8 @@ parameters. .. class:: Union(expr1, expr2, **extra) -*Availability*: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite +*Availability*: MySQL (≥ 5.6.1), `PostGIS +<https://postgis.net/docs/ST_Union.html>`__, Oracle, SpatiaLite Accepts two geographic fields or expressions and returns the union of both geometries.