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

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

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

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

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

GeoJSON

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]}

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).

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, когда координаты геодезические, возвращается значение 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)

Доступность: MySQL, 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\nили MULTI*\nполя). Возвращает 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

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