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

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

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

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

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

Представление в формате GeoJSON

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

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

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

Представление в формате KML

class AsKML(expression, precision=8, **extra) [source]

Доступность: 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) [source]

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

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Scalable Vector Graphics (SVG).

AsWKB

class AsWKB(expression, **extra) [source]

Доступность: 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) [source]

Доступность: 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) [source]

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

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

BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra) [source]

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

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

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

Centroid

class Centroid(expression, **extra) [source]

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

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

ClosestPoint

class ClosestPoint(expr1, expr2, **extra) [source]

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

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

Difference

class Difference(expr1, expr2, **extra) [source]

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

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

Distance

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

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

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

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

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

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

ForcePolygonCW

class ForcePolygonCW(expression, **extra) [source]

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

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

FromWKB

class FromWKB(expression, srid=0, **extra) [source]

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

Создаёт геометрию из двоичного представления Well-known (WKB). Необязательный аргумент srid позволяет указать SRID полученной геометрии. srid игнорируется в Oracle.

FromWKT

class FromWKT(expression, srid=0, **extra) [source]

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

Создаёт геометрию из текстового представления Well-known (WKT). Необязательный аргумент srid позволяет указать SRID полученной геометрии. srid игнорируется в Oracle.

GeoHash

class GeoHash(expression, precision=None, **extra) [source]

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

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

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

GeometryDistance

class GeometryDistance(expr1, expr2, **extra) [source]

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

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

Intersection

class Intersection(expr1, expr2, **extra) [source]

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

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

IsEmpty

class IsEmpty(expr) [source]

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

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

IsValid

class IsValid(expr) [source]

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

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

Length

class Length(expression, spheroid=True, **extra) [source]

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

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

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

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

LineLocatePoint

class LineLocatePoint(linestring, point, **extra) [source]

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

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

MakeValid

class MakeValid(expr) [source]

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

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

MemSize

class MemSize(expression, **extra) [source]

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

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

NumGeometries

class NumGeometries(expression, **extra) [source]

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

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

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

NumPoints

class NumPoints(expression, **extra) [source]

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

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

В MySQL, возвращает None для любой не-LINESTRING геометрии.

Perimeter

class Perimeter(expression, **extra) [source]

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

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

PointOnSurface

class PointOnSurface(expression, **extra) [source]

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

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

Reverse

class Reverse(expression, **extra) [source]

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

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

Scale

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

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

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

SnapToGrid

class SnapToGrid(expression, *args, **extra) [source]

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

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

SymDifference

class SymDifference(expr1, expr2, **extra) [source]

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

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

Transform

class Transform(expression, srid, **extra) [source]

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

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

Translate

class Translate(expression, x, y, z=0.0, **extra) [source]

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

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

Union

class Union(expr1, expr2, **extra) [source]

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

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