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

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

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

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

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

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

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