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

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

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

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

SVG

class AsSVG(expression, relative=False, precision=8, **extra) [source]

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

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

Окружность ограничивающего прямоугольника

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]

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

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

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

ForceRHR

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

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

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

GeoHash

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

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

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

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

Intersection

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

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

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

IsValid

class IsValid(expr) [source]

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

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

Length

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

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

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

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

MakeValid

class MakeValid(expr) [source]

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

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

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.

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]

Доступность: MySQL (≥ 5.6.1), 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

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