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

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

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

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

Функция GeoJSON

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

Доступность: PostGIS, SpatiaLite (≥ 3.0)

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

Доступность: PostGIS, SpatiaLite (≥ 2.4.0-RC4)

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

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

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

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

BoundingCircle

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

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

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

Centroid

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

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

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

Difference

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

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

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

Distance

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

Доступность: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

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

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

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

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

ForceRHR

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

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

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

GeoHash

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

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

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

Intersection

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

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

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

Length

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

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

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

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

MemSize

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

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

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

NumGeometries

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

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

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

NumPoints

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

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

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

Perimeter

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

Доступность: PostGIS, Oracle, SpatiaLite (≥ 4.0)

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

PointOnSurface

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

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

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

Reverse

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

Доступность: PostGIS, Oracle, SpatiaLite (≥ 4.0)

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

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 (≥ 3.1)

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

SymDifference

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

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

Доступность: MySQL (≥ 5.6.1), PostGIS, Oracle, SpatiaLite

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