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

Функции, описанные на этой странице, позволяют пользователям получать доступ к функциям географической базы данных для использования в аннотациях, агрегациях или фильтрах в Django.

Пример:

>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length('line')).filter(length__gt=100)

Не все бэкэнды поддерживают все функции, поэтому обратитесь к документации каждой функции, чтобы узнать, поддерживает ли ваш бэкэнд базы данных нужную функцию. Если вы вызываете географическую функцию на бэкенде, который её не поддерживает, вы получите исключение NotImplementedError.

Краткое описание функций:

Описание площади

class Area(expression, **extra)

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

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

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

Формат GeoJSON

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)

Доступность: MariaDB (≥ 10.2.4), MySQL (≥ 5.7.5), 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]}

Формат GML

class AsGML(expression, version=2, precision=8, **extra)

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

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Географического языка разметки (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>

Формат KML

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>

Формат SVG

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

Azimuth

class Azimuth(point_a, point_b, **extra)

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

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

BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra)

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

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

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

Centroid

class Centroid(expression, **extra)

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

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

Difference

class Difference(expr1, expr2, **extra)

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

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

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

Envelope

class Envelope(expression, **extra)

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

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

ForcePolygonCW

class ForcePolygonCW(expression, **extra)

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

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

GeoHash

class GeoHash(expression, precision=None, **extra)

Доступность: MySQL (≥ 5.7.5), PostGIS, SpatiaLite (LWGEOM)

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

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

GeometryDistance

class GeometryDistance(expr1, expr2, **extra)

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

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

Intersection

class Intersection(expr1, expr2, **extra)

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

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

IsValid

class IsValid(expr)

Доступность: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite (LWGEOM)

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

Length

class Length(expression, spheroid=True, **extra)

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

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

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

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

LineLocatePoint

class LineLocatePoint(linestring, point, **extra)

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

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

MakeValid

class MakeValid(expr)

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

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

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.

Perimeter

class Perimeter(expression, **extra)

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

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

PointOnSurface

class PointOnSurface(expression, **extra)

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

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

Reverse

class Reverse(expression, **extra)

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

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

Scale

class Scale(expression, x, y, z=0.0, **extra)

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

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

SnapToGrid

class SnapToGrid(expression, *args, **extra)

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

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

SymDifference

class SymDifference(expr1, expr2, **extra)

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

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

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 числовыми параметрами.

Union

class Union(expr1, expr2, **extra)

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

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