Функции географических баз данных

Area

class Area(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает площадь поля как величину Area.

MySQL и SpatiaLite без LWGEOM/RTTOPO не поддерживают вычисление площади для географических систем пространственной привязки.

Distance

class Distance(expr1, expr2, spheroid=None, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает два географических поля или выражения и возвращает расстояние между ними в виде объекта Distance. В MySQL при геодезических координатах возвращается значение типа float.

На серверах, поддерживающих вычисление расстояния для геодезических координат, подходящая функция сервера выбирается автоматически в зависимости от значения SRID геометрий (например, ST_DistanceSphere в PostGIS).

При вычислении расстояний по геодезическим (угловым) координатам, как в случае с используемым по умолчанию SRID WGS84 (4326), можно задать именованный аргумент spheroid, чтобы выбрать, будет ли вычисление выполняться на основе обычной сферы (менее точно, но с меньшими затратами ресурсов) или сфероида (точнее, но с большими затратами ресурсов).

В следующем примере вычисляется расстояние от города Хобарт до каждого другого объекта PointField в наборе запросов AustraliaCity:

>>> 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
...

GeometryDistance

class GeometryDistance(expr1, expr2, **extra) [исходный код]

Доступность: PostGIS

Принимает два географических поля или выражения и возвращает расстояние между ними. При использовании в предложении order_by() эта функция обеспечивает выборку ближайших соседей с использованием индекса.

Length

class Length(expression, spheroid=True, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение типа «линейная строка» или «мультилинейная строка» и возвращает его длину как величину Distance.

В PostGIS и SpatiaLite при угловых геодезических координатах можно с помощью именованного аргумента spheroid указать, должно ли вычисление выполняться на основе обычной сферы (менее точно, но с меньшими затратами ресурсов) или сфероида (точнее, но с большими затратами ресурсов).

MySQL не поддерживает вычисление длины для географических систем пространственной привязки.

Perimeter

class Perimeter(expression, **extra) [исходный код]

Доступность: PostGIS, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает периметр геометрического поля как объект Distance.

Azimuth

class Azimuth(point_a, point_b, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Возвращает азимут в радианах отрезка, заданного указанными геометрическими точками, или None, если точки совпадают. Азимут — это угол, отсчитываемый от севера по часовой стрелке: север = 0; восток = π/2; юг = π; запад = 3π/2.

BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra) [исходный код]

Доступность: PostGIS, Oracle, SpatiaLite 5.1+

Принимает одно географическое поле или выражение и возвращает наименьший полигон в форме круга, полностью содержащий геометрию.

Параметр num_seg используется только в PostGIS.

Centroid

class Centroid(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает значение centroid геометрии.

ClosestPoint

class ClosestPoint(expr1, expr2, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает два географических поля или выражения и возвращает двумерную точку геометрии A, ближайшую к геометрии B.

Envelope

class Envelope(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию, представляющую ограничивающую рамку этой геометрии.

LineLocatePoint

class LineLocatePoint(linestring, point, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Возвращает число с плавающей точкой от 0 до 1, представляющее положение ближайшей точки на linestring к указанной point в виде доли длины двумерной линии.

PointOnSurface

class PointOnSurface(expression, **extra) [исходный код]

Доступность: PostGIS, MariaDB, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию Point, гарантированно лежащую на поверхности поля; в противном случае возвращает None.

Difference

class Difference(expr1, expr2, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает два географических поля или выражения и возвращает геометрическую разность, то есть часть геометрии A, не пересекающуюся с геометрией B.

Intersection

class Intersection(expr1, expr2, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает два географических поля или выражения и возвращает геометрическое пересечение между ними.

SymDifference

class SymDifference(expr1, expr2, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает два географических поля или выражения и возвращает геометрическую симметрическую разность (объединение без пересечения) заданных параметров.

Union

class Union(expr1, expr2, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает два географических поля или выражения и возвращает объединение обеих геометрий.

ForcePolygonCW

class ForcePolygonCW(expression, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает изменённую версию полигона или мультиполигона, в которой все внешние кольца ориентированы по часовой стрелке, а все внутренние — против часовой стрелки. Геометрии, не являющиеся полигонами, возвращаются без изменений.

MakeValid

class MakeValid(expr) [исходный код]

Доступность: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Принимает географическое поле или выражение и пытается преобразовать значение в корректную геометрию, не теряя ни одной исходной вершины. Уже корректные геометрии возвращаются без изменений. Простые полигоны могут стать мультиполигонами, а размерность результата может быть меньше размерности исходной геометрии.

Reverse

class Reverse(expression, **extra) [исходный код]

Доступность: PostGIS, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию с обратным порядком координат.

Rotate

class Rotate(expression, angle, origin=None, **extra) [исходный код]

Поворачивает геометрию на заданный angle вокруг начала координат. При желании поворот можно выполнить вокруг точки, заданной параметром origin.

Scale

class Scale(expression, x, y, z=0.0, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию с масштабированными координатами, умноженными на параметры x, y и, при необходимости, z.

SnapToGrid

class SnapToGrid(expression, *args, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию, все точки которой привязаны к заданной сетке. Способ привязки геометрии к сетке зависит от количества переданных числовых аргументов (типа float, integer или long).

Transform

class Transform(expression, srid, **extra) [исходный код]

Доступность: PostGIS, Oracle, SpatiaLite

Принимает географическое поле или выражение и целочисленный код SRID, возвращая геометрию, преобразованную в систему пространственной привязки, заданную параметром srid.

Translate

class Translate(expression, x, y, z=0.0, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает геометрию со смещёнными координатами; смещение задаётся числовыми параметрами x, y и, при необходимости, z.

FromWKB

class FromWKB(expression, srid=0, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Создаёт геометрию из представления WKB (Well-known binary). Необязательный аргумент srid позволяет указать SRID результирующей геометрии. В Oracle srid игнорируется.

FromWKT

class FromWKT(expression, srid=0, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Создаёт геометрию из представления WKT (Well-known text). Необязательный аргумент srid позволяет указать SRID результирующей геометрии. В Oracle srid игнорируется.

AsGeoJSON

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате GeoJSON. Обратите внимание: результат не является полной структурой GeoJSON, а содержит только содержимое ключа geometry структуры GeoJSON. См. также Сериализатор GeoJSON.

Пример:

>>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
{"type":"Point","coordinates":[-87.65018,41.85039]}

AsGML

class AsGML(expression, version=2, precision=8, **extra) [исходный код]

Доступность: Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии на языке Geographic Markup Language (GML).

Пример:

>>> 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>

AsKML

class AsKML(expression, precision=8, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии на языке Keyhole Markup Language (KML).

Пример:

>>> 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>

AsSVG

class AsSVG(expression, relative=False, precision=8, **extra) [исходный код]

Доступность: PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Scalable Vector Graphics (SVG).

AsWKB

class AsWKB(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Well-known binary (WKB).

Пример:

>>> 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) [исходный код]

Доступность: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Well-known text (WKT).

Пример:

>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'

GeoHash

class GeoHash(expression, precision=None, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате GeoHash.

Именованный аргумент precision определяет количество символов в результате.

IsEmpty

class IsEmpty(expr) [исходный код]

Доступность: PostGIS

Принимает географическое поле или выражение и проверяет, является ли значение пустой геометрией. Возвращает True, если значение пустое, и False в противном случае.

IsValid

class IsValid(expr) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает географическое поле или выражение и проверяет, корректно ли оно сформировано. Возвращает True, если значение является корректной геометрией, и False в противном случае.

GeometryType

class GeometryType(expr) [исходный код]

Доступность: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Принимает географическое поле или выражение и возвращает тип геометрии.

MemSize

class MemSize(expression, **extra) [исходный код]

Доступность: PostGIS

Принимает одно географическое поле или выражение и возвращает размер памяти (количество байтов), занимаемый полем геометрии.

NumGeometries

class NumGeometries(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает количество геометрий, если поле геометрии представляет собой коллекцию (например, поле GEOMETRYCOLLECTION или MULTI*). Для одиночных геометрий возвращает 1.

В MySQL для одиночных геометрий возвращает None.

NumPoints

class NumPoints(expression, **extra) [исходный код]

Доступность: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Принимает одно географическое поле или выражение и возвращает количество точек в геометрии.

В MySQL для любой геометрии, не являющейся LINESTRING, возвращает None.