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

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

AsGeoJSON

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

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

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

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

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

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, возвращает None для любой не-LINESTRING геометрии.

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

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