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

Функции, документированные на этой странице, позволяют пользователям получить доступ к функциям географических баз данных для использования в аннотациях, агрегациях или фильтрах в 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 Envelope Union Scale   AsSVG NumGeometries
Perimeter LineLocatePoint PointOnSurface   SnapToGrid Transform Translate FromWKB FromWKT AsWKB AsWKT GeoHash NumPoints

Area

class Area(expression, **extra)

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

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

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

AsGeoJSON

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

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

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

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

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

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

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

AsWKB

class AsWKB(expression, **extra)

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

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

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

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

BoundingCircle

class BoundingCircle(expression, num_seg=48, **extra)

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

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

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

Centroid

class Centroid(expression, **extra)

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

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

Difference

class Difference(expr1, expr2, **extra)

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

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

Distance

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

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

Примечание

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

Envelope

class Envelope(expression, **extra)

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

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

ForcePolygonCW

class ForcePolygonCW(expression, **extra)

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

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

FromWKB

New in Django 4.2.
class FromWKB(expression, **extra)

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

Создает геометрию из представления Well-known binary (WKB).

FromWKT

New in Django 4.2.
class FromWKT(expression, **extra)

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

Создает геометрию из представления Well-known text (WKT).

GeoHash

class GeoHash(expression, precision=None, **extra)

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

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

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

GeometryDistance

class GeometryDistance(expr1, expr2, **extra)

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

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

Intersection

class Intersection(expr1, expr2, **extra)

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

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

IsEmpty

New in Django 4.2.
class IsEmpty(expr)

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

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

IsValid

class IsValid(expr)

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

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

Length

class Length(expression, spheroid=True, **extra)

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

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

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

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

LineLocatePoint

class LineLocatePoint(linestring, point, **extra)

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

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

MakeValid

class MakeValid(expr)

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

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

MemSize

class MemSize(expression, **extra)

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

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

NumGeometries

class NumGeometries(expression, **extra)

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

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

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

NumPoints

class NumPoints(expression, **extra)

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

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

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

Perimeter

class Perimeter(expression, **extra)

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

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

PointOnSurface

class PointOnSurface(expression, **extra)

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

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

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

SymDifference

class SymDifference(expr1, expr2, **extra)

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

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

Transform

class Transform(expression, srid, **extra)

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

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

Примечание

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

Translate

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

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

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

Union

class Union(expr1, expr2, **extra)

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

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

Вернуться на верх