Функции геопространственной базы данных

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

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

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

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

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

Difference

class Difference(expr1, expr2, **extra)

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

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

Distance

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

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

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

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

ForcePolygonCW

class ForcePolygonCW(expression, **extra)

Доступность: 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, 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 не поддерживает вычисления длины для географических систем координат.

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)

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

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

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

NumPoints

class NumPoints(expression, **extra)

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

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

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

Perimeter

class Perimeter(expression, **extra)

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

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

PointOnSurface

class PointOnSurface(expression, **extra)

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

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

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

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