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

Функции, описанные на этой странице, позволяют пользователям получить доступ к функциям географической базы данных, которые можно использовать в аннотациях, агрегациях или фильтрах в 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)

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

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

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

AsGeoJSON

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

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

Азимут

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)

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

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

Difference

class Difference(expr1, expr2, **extra)

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

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

Distance

class Distance(expr1, expr2, spheroid=None, **extra)

Доступность: MySQL (≥ 5.6.1), 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)

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

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

ForceRHR

class ForceRHR(expression, **extra)

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

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

GeoHash

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

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

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

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

Intersection

class Intersection(expr1, expr2, **extra)

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

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

IsValid

class IsValid(expr)

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

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

Length

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

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

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

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

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

LineLocatePoint

class LineLocatePoint(linestring, point, **extra)

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

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

MakeValid

class MakeValid(expr)

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

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

MemSize

class MemSize(expression, **extra)

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

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

NumGeometries

class NumGeometries(expression, **extra)

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

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

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

NumPoints

class NumPoints(expression, **extra)

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

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

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

Perimeter

class Perimeter(expression, **extra)

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

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

PointOnSurface

class PointOnSurface(expression, **extra)

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

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

Доступность: MySQL (≥ 5.6.1), 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)

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

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