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

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

Пример:

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

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

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

Area

class Area(expression, **extra)

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

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

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

AsGeoJSON

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

Доступность: MariaDB, 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]}

AsGML

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>

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

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

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

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

Centroid

class Centroid(expression, **extra)

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

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

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/RTTOPO)

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

Принимает географическое поле или выражение и проверяет, является ли значение правильно сформированной геометрией. Возвращает 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/RTTOPO)

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

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

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

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

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