Функции географической базы данных ¶
Функции, описанные на этой странице, предоставляют пользователям доступ к функциям географической базы данных, которые можно использовать в аннотациях, агрегатах или фильтрах с 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 |
IsValid |
Distance |
BoundingCircle |
Intersection |
MakeValid |
AsGML |
MemSize |
GeometryDistance |
Centroid |
SymDifference |
Reverse |
AsKML |
NumGeometries |
Length |
Envelope |
Union |
Scale |
AsSVG |
NumPoints |
Perimeter |
LineLocatePoint |
SnapToGrid |
AsWKB |
||
PointOnSurface |
Transform |
AsWKT |
|||
Translate |
GeoHash |
Area
¶
-
class
Area
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , Oracle, PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает площадь поля в качестве меры Area
.
MySQL и SpatiaLite без LWGEOM не поддерживают вычисления площадей для объектов географической системы координат.
AsGeoJSON
¶
-
class
AsGeoJSON
( выражение , bbox = False , crs = False , precision = 8 , ** extra ) ¶
Доступность : MariaDB (≥ 10.2.4), MySQL (≥ 5.7.5), 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. |
Поддержка Oracle
AsGML
¶
-
class
AsGML
( выражение , версия = 2 , точность = 8 , ** дополнительно ) ¶
Доступность : Oracle, 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>
Именованный параметр | Описание |
---|---|
precision |
Указывает количество значащих цифр координат представления GML, по умолчанию 8. Игнорируется в Oracle. |
version |
Указывает версию GML для использования: 2 (по умолчанию) или 3. |
AsKML
¶
-
class
AsKML
( выражение , точность = 8 , ** дополнительно ) ¶
Доступность : PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает представление геометрического поля на языке разметки 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>
Именованный параметр | Описание |
---|---|
precision |
Этот параметр можно использовать для указания количества значащих цифр координат представления KML, значение по умолчанию - 8. |
Недокументированный version
параметр удален.
AsSVG
¶
-
class
AsSVG
( выражение , relative = False , precision = 8 , ** extra ) ¶
Доступность : PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает представление геометрического поля в виде масштабируемой векторной графики (SVG) .
Именованный параметр | Описание |
---|---|
relative |
Если установлено значение True , данные пути представлены в виде относительных смещений. Значение по умолчанию False означает, что используются абсолютные смещения. |
precision |
Этот параметр может использоваться для указания количества значащих цифр координат представления SVG, по умолчанию - 8. |
AsWKB
¶
-
class
AsWKB
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , Oracle, PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает широко известное двоичное (WKB) представление геометрии.
Пример:
>>> bytes(City.objects.annotate(wkb=AsWKB('point')).get(name='Chelyabinsk').wkb)
b'\x01\x01\x00\x00\x00]3\xf9f\x9b\[email protected]\x00X\x1d9\xd2\[email protected]'
AsWKT
¶
-
class
AsWKT
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , Oracle, PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает широко известное текстовое (WKT) представление геометрии.
Пример:
>>> City.objects.annotate(wkt=AsWKT('point')).get(name='Chelyabinsk').wkt
'POINT (55.137555 61.451728)'
Azimuth
¶
-
класс
Azimuth
( point_a , point_b , ** extra ) ¶
Доступность : PostGIS , SpatiaLite (LWGEOM)
Возвращает азимут в радианах сегмента, определенного заданными геометрическими точками, или None
если две точки совпадают. Азимут - это угол, начинающийся с севера и положительный по часовой стрелке: север = 0
; равно = π/2
; юг = π
; запад = 3π/2
.
BoundingCircle
¶
-
class
BoundingCircle
( выражение , num_seg = 48 , ** extra ) ¶
Доступность : PostGIS , Oracle
Принимает одно географическое поле или выражение и возвращает наименьший многоугольник круга, который может полностью содержать геометрический объект.
Параметр num_seg
и используется только с PostGIS.
Centroid
¶
-
class
Centroid
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , PostGIS , Oracle, SpatiaLite
Принимает одно географическое поле или выражение и возвращает значение центроида геометрического объекта.
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 число с плавающей запятой возвращается, если координаты имеют геодезический тип.
Для баз данных, которые позволяют рассчитывать расстояния с геодезическими координатами, правильная функция базы данных выбирается автоматически на основе значения 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
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , Oracle , PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает геометрический объект, представляющий ограничивающий прямоугольник объекта.
ForcePolygonCW
¶
-
class
ForcePolygonCW
( выражение , ** extra ) ¶
Доступность : PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает измененную версию (мульти) многоугольника, где все внешние пути идут по часовой стрелке, а все внутренние пути - против часовой стрелки. Геометрии, не являющиеся полигонами, возвращаются без изменений.
GeoHash
¶
-
class
GeoHash
( выражение , точность = None , ** extra ) ¶
Доступность : MySQL (≥ 5.7.5), PostGIS , SpatiaLite (LWGEOM)
Принимает одно географическое поле или выражение и возвращает представление геометрического поля GeoHash .
Именованный параметр precision
контролирует количество символов в результате.
GeometryDistance
¶
-
class
GeometryDistance
( expr1 , expr2 , ** extra ) ¶
Доступность : PostGIS
Принимает два географических поля или выражения и возвращает расстояние между ними. При использовании в предложении order_by()
он предоставляет наборы результатов ближайшего соседа на основе индексов.
Intersection
¶
-
class
Intersection
( expr1 , expr2 , ** extra ) ¶
Доступность : MariaDB, MySQL , PostGIS , Oracle, SpatiaLite
Принимает два географических поля или выражения и возвращает их геометрическое пересечение.
IsValid
¶
-
класс
IsValid
( выражение ) ¶
Доступность : MySQL (≥ 5.7.5), PostGIS , Oracle, SpatiaLite (LWGEOM)
Принимает географическое поле или выражение и проверяет, правильно ли сформировано значение. Возвращает True
, является ли значение допустимым геометрическим объектом, а False
если нет.
Length
¶
-
class
Length
( выражение , spheroid = True , ** extra ) ¶
Доступность : MariaDB, MySQL , Oracle, PostGIS , SpatiaLite
Принимает однострочное или многострочное географическое поле или выражение и возвращает его длину в качестве меры Distance
.
С PostGIS или SpatiaLite, и когда координаты являются геодезическими (углы), вы можете определить с помощью указанного параметра spheroid
, должны ли вычисления выполняться в соответствии с простой сферой (менее точной, менее ресурсоемкой) или сфероидом (более точно, более ресурсоемкий).
MySQL не поддерживает вычисления длины для объектов географической системы отсчета.
LineLocatePoint
¶
-
class
LineLocatePoint
( linestring , point , ** extra ) ¶
Доступность : PostGIS , SpatiaLite
Возвращает число с плавающей запятой от 0 до 1, представляющее расположение точки, linestring
ближайшей к point
указанной, как часть длины 2D-линии.
MakeValid
¶
-
класс
MakeValid
( выражение ) ¶
Доступность : PostGIS , SpatiaLite (LWGEOM)
Принимает географическое поле или выражение и пытается преобразовать значение в допустимую геометрию без потери каких-либо исходных сегментов. Уже действительные объекты возвращаются как есть. Простые многоугольники могут стать мультиполигонами, и результат может быть на одно измерение меньше входного объекта.
MemSize
¶
-
class
MemSize
( выражение , ** extra ) ¶
Доступность : PostGIS
Принимает одно географическое поле или выражение и возвращает объем памяти (в байтах), потребляемый геометрическим полем.
NumGeometries
¶
-
class
NumGeometries
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , PostGIS , Oracle, SpatiaLite
Принимает одно поле или географическое выражение и возвращает количество геометрических объектов в случае, если поле является коллекцией (например, GEOMETRYCOLLECTION
или полем MULTI*
). Возвращает 1 для уникальных геометрических объектов.
В MySQL возвращается None
для отдельных геометрических объектов.
NumPoints
¶
-
class
NumPoints
( выражение , ** extra ) ¶
Доступность : MariaDB, MySQL , PostGIS , Oracle, SpatiaLite
Принимает одно географическое поле или выражение и возвращает количество точек геометрического объекта.
В MySQL возвращается None
для геометрических объектов, отличных от LINESTRING
.
Perimeter
¶
-
class
Perimeter
( выражение , ** extra ) ¶
Доступность : PostGIS , Oracle, SpatiaLite
Принимает одно географическое поле или выражение и возвращает периметр поля в качестве меры Distance
.
PointOnSurface
¶
-
class
PointOnSurface
( выражение , ** extra ) ¶
Доступность : PostGIS , MariaDB, Oracle, SpatiaLite
Принимает одно географическое поле или выражение и возвращает объект, Point
который определенно находится на поверхности поля; в противном случае верните None
.
Reverse
¶
-
class
Reverse
( выражение , ** extra ) ¶
Доступность : PostGIS , Oracle, SpatiaLite
Принимает одно географическое поле или выражение и возвращает геометрический объект с обратными координатами.
Scale
¶
-
class
Scale
( выражение , x , y , z = 0.0 , ** extra ) ¶
Доступность : PostGIS , SpatiaLite
Принимает одно поле или географическое выражение и возвращает геометрию с масштабированными координатами, умноженными на параметры x
, y
и, при необходимости z
.
SnapToGrid
¶
-
класс
SnapToGrid
( выражение , * аргументы , ** дополнительные ) ¶
Доступность : PostGIS , SpatiaLite
Принимает одно географическое поле или выражение и возвращает геометрический объект, все точки которого соответствуют заданной сетке. Способ размещения геометрического объекта в сетке зависит от количества предоставленных числовых параметров (с плавающей запятой, целых или длинных целых чисел).
Количество параметров | Описание |
---|---|
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
( выражение , srid , ** extra ) ¶
Доступность : PostGIS , Oracle, SpatiaLite
Принимает географическое поле или выражение и целочисленный код SRID и возвращает преобразованный геометрический объект в системе пространственной привязки, указанной параметром srid
.
Заметка
Соответствие между номерами SRID и системами пространственной привязки может зависеть от используемого пространственного механизма. Например, номера SRID, используемые Oracle, могут не совпадать с номерами, используемыми PostGIS.