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

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

Пример:

>>> from django.contrib.gis.db.models.functions import Length
>>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)

Не все бэкэнды поддерживают все функции, поэтому обратитесь к документации каждой функции, чтобы узнать, поддерживает ли ваш бэкэнд базы данных нужную вам функцию. Если вы вызываете географическую функцию в бэкэнде, который её не поддерживает, вы получите исключение NotImplementedError.

Краткое описание функций:

Измерение	Взаимосвязи	Операции	Редакторы	Формат ввода	Формат вывода	Разное
`Area`	`Azimuth`	`Difference`	`ForcePolygonCW`		`AsGeoJSON`	`IsEmpty`
`Distance`	`BoundingCircle`	`Intersection`	`MakeValid`		`AsGML`	`IsValid`
`GeometryDistance`	`Centroid`	`SymDifference`	`Reverse`		`AsKML`	`MemSize`
`Length`	`ClosestPoint`	`Union`	`Scale`		`AsSVG`	`NumGeometries`
`Perimeter`	`Envelope` `LineLocatePoint` `PointOnSurface`		`SnapToGrid` `Transform` `Translate`	`FromWKB` `FromWKT`	`AsWKB` `AsWKT` `GeoHash`	`NumPoints`

`Area`

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

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

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

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

`AsGeoJSON`

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

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

Ключевое слово	Описание
`bbox`	Установите это значение в `True`, если вы хотите, чтобы прямоугольник ограничительной рамки был включён в возвращаемый GeoJSON. Игнорируется в Oracle.
`crs`	Установите это значение в `True`, если вы хотите, чтобы система координат была включена в возвращаемый GeoJSON. Игнорируется в MySQL и Oracle.
`precision`	Может быть использовано для указания количества значащих цифр для координат в представлении GeoJSON — значение по умолчанию равно 8. Игнорируется в Oracle.

`AsGML`

class AsGML(expression, version=2, precision=8, **extra) [source]

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

Ключевое слово аргумента	Описание
`precision`	Указывает количество значащих цифр для координат в представлении GML — значение по умолчанию равно 8. Игнорируется в Oracle.
`version`	Указывает используемую версию GML: 2 (по умолчанию) или 3.

`AsKML`

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>

Ключевое слово аргумента	Описание
`precision`	Это ключевое слово можно использовать для указания количества значащих цифр для координат в представлении KML — значение по умолчанию равно 8.

`AsSVG`

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

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

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

Ключевое слово аргумента	Описание
`relative`	Если установлено в `True`, данные пути будут реализованы в терминах относительных перемещений. По умолчанию установлено значение `False`, что означает использование абсолютных перемещений.
`precision`	Это ключевое слово можно использовать для указания количества значащих цифр для координат в представлении SVG — значение по умолчанию равно 8.

`AsWKB`

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

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

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

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

Принимает одно географическое поле или выражение и возвращает представление геометрии в формате Well-known text (WKT).

Пример:

>>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
'POINT (55.137555 61.451728)'

`Azimuth`

class Azimuth(point_a, point_b, **extra) [source]

Доступность: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Возвращает азимут в радианах сегмента, определенного заданными точечными геометриями, или None, если две точки совпадают. Азимут — это угол, отсчитываемый от северного направления и положительный по часовой стрелке: север = 0; восток = π/2; юг = π; запад = 3π/2.

`BoundingCircle`

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

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

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

Параметр num_seg используется только в PostGIS.

Изменено в Django 5.1:

Добавлена поддержка SpatiaLite 5.1+.

`Centroid`

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

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

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

`ClosestPoint`

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

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

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

`Difference`

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

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

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

Расстояние

Функция расстояния [source]

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

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

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

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

В следующем примере вычисляется расстояние от города Хобарт до всех остальных точек в наборе запросов 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
...

Примечание

Поскольку атрибут distance является объектом расстояния, можно легко выразить значение в единицах измерения по своему выбору. Например, city.distance.mi — это значение расстояния в милях, а city.distance.km — значение расстояния в километрах. Подробности использования и список Поддерживаемых единиц измерения см. в разделе Объекты измерений.

Оборачивание

Функция оборачивания [source]

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

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

Принудительное направление многоугольника по часовой стрелке

Функция принудительного направления многоугольника по часовой стрелке [source]

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

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

Из WKB

Функция из WKB [source]

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

Создаёт геометрию из представления «известного бинарного» (WKB). Необязательный параметр srid позволяет указать SRID полученной геометрии. srid игнорируется в Oracle.

Изменено в Django 5.1:

Добавлен параметр srid.

Из WKT

Функция из WKT [source]

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

Создаёт геометрию из представления «известного текста» (WKT). Необязательный параметр srid позволяет указать SRID полученной геометрии. srid игнорируется в Oracle.

Изменено в Django 5.1:

Добавлен параметр srid.

GeoHash

Функция GeoHash [source]

Доступность: MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

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

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

Расстояние между геометриями

Функция расстояния между геометриями [source]

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

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

Пересечение

Функция пересечения [source]

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

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

Пусто

Функция проверки на пустоту [source]

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

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

Действительно

Функция проверки валидности [source]

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

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

`Length`

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

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

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

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

MySQL не поддерживает вычисления длины на географических СКСР.

`LineLocatePoint`

class LineLocatePoint(linestring, point, **extra) [source]

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

Возвращает число с плавающей точкой от 0 до 1, представляющее положение ближайшей точки на linestring до заданной point, как долю длины 2D линии.

`MakeValid`

class MakeValid(expr) [source]

Доступность: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

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

`MemSize`

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

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

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

`NumGeometries`

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

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

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

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

`NumPoints`

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

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

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

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

`Perimeter`

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

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

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

`PointOnSurface`

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

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

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

`Reverse`

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

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

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

`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

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

Количество аргументов	Описание
1	Один размер для привязки сетки X и Y.
2	Размеры X и Y для привязки сетки.
4	Размеры X, Y и соответствующие начальные значения X, Y.

`SymDifference`

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

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

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

`Transform`

class Transform(expression, srid, **extra) [source]

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

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

Примечание

Какой пространственной системе координат соответствует целочисленный SRID, может зависеть от используемой пространственной базы данных. Другими словами, номера SRID, используемые в Oracle, не обязательно совпадают с номерами SRID, используемыми в PostGIS.

`Translate`

class Translate(expression, x, y, z=0.0, **extra) [source]

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

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

`Union`

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

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

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

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/5.2/ref/contrib/gis/functions/