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

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

Представление в формате 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

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

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

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

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

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

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 возвращает 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

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

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

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