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

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

classArea ( выражение , ** extra )

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

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

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

AsGeoJSON

classAsGeoJSON ( выражение , 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.
Изменено в Django 3.1:

Поддержка Oracle

AsGML

classAsGML ( выражение , версия = 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

classAsKML ( выражение , точность = 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.
Изменено в Django 3.1:

Недокументированный version параметр удален.

AsSVG

classAsSVG ( выражение , relative = False , precision = 8 , ** extra )

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

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

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

AsWKB

classAsWKB ( выражение , ** extra )
Новое в Django 3.1.

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

classAsWKT ( выражение , ** extra )
Новое в Django 3.1.

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

classBoundingCircle ( выражение , num_seg = 48 , ** extra )

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

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

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

Centroid

classCentroid ( выражение , ** extra )

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

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

Difference

classDifference ( expr1 , expr2 , ** extra )

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

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

Distance

classDistance ( 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

classEnvelope ( выражение , ** extra )

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

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

ForcePolygonCW

classForcePolygonCW ( выражение , ** extra )

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

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

GeoHash

classGeoHash ( выражение , точность = None , ** extra )

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

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

Именованный параметр precision контролирует количество символов в результате.

GeometryDistance

classGeometryDistance ( expr1 , expr2 , ** extra )
Новое в Django 3.0.

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

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

Intersection

classIntersection ( expr1 , expr2 , ** extra )

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

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

IsValid

классIsValid ( выражение )

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

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

Length

classLength ( выражение , spheroid = True , ** extra )

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

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

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

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

LineLocatePoint

classLineLocatePoint ( linestring , point , ** extra )

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

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

MakeValid

классMakeValid ( выражение )

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

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

MemSize

classMemSize ( выражение , ** extra )

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

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

NumGeometries

classNumGeometries ( выражение , ** extra )

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

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

В MySQL возвращается None для отдельных геометрических объектов.

NumPoints

classNumPoints ( выражение , ** extra )

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

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

В MySQL возвращается None для геометрических объектов, отличных от LINESTRING .

Perimeter

classPerimeter ( выражение , ** extra )

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

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

PointOnSurface

classPointOnSurface ( выражение , ** extra )

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

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

Reverse

classReverse ( выражение , ** extra )

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

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

Scale

classScale ( выражение , 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

classSymDifference ( expr1 , expr2 , ** extra )

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

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

Transform

classTransform ( выражение , srid , ** extra )

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

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

Заметка

Соответствие между номерами SRID и системами пространственной привязки может зависеть от используемого пространственного механизма. Например, номера SRID, используемые Oracle, могут не совпадать с номерами, используемыми PostGIS.

Translate

classTranslate ( выражение , x , y , z = 0.0 , ** extra )

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

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

Union

classUnion ( expr1 , expr2 , ** extra )

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

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

Copyright ©2020 All rights reserved