Справочник API GeoQuerySet

class GeoQuerySet(model=None)

Пространственные запросы

Пространственные запросы в этом разделе доступны для GeometryField.

Для введения см. введение в пространственные запросы. Для обзора запросов, совместимых с определённым пространственным бэкэндом, см. таблицу совместимости пространственных запросов.

Краткое описание bbcontains

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

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

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

Краткое описание bboverlaps

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

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

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

Краткое описание contained

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

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

Пример:

Zipcode.objects.filter(poly__contained=geom)

Краткое описание contains

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

Проверяет, содержит ли геометрия поля геометрию запроса.

Пример:

Zipcode.objects.filter(poly__contains=geom)

Краткое описание contains_properly

Доступно: PostGIS

Возвращает true, если геометрия запроса пересекает внутреннюю область геометрии поля, но не границу (или внешнюю область). [4]

Пример:

Zipcode.objects.filter(poly__contains_properly=geom)

Краткое описание coveredby

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

Проверяет, что ни одна точка в геометрии поля не находится вне геометрии запроса. [3]

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

Краткое описание covers

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

Проверяет, что ни одна точка в геометрии запроса не находится вне геометрии поля. [3]

Пример:

Zipcode.objects.filter(poly__covers=geom)

Краткое описание crosses

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

Проверяет, пересекает ли геометрия поля геометрию запроса.

Пример:

Zipcode.objects.filter(poly__crosses=geom)

Краткое описание disjoint

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

Проверяет, не соприкасается ли геометрия поля с геометрией запроса.

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

Краткое описание equals

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

Краткое описание same_as, то же самое

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

Краткое описание intersects

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

Проверяет, пересекаются ли геометрия поля и геометрия запроса.

Пример:

Zipcode.objects.filter(poly__intersects=geom)

Краткое описание overlaps

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

Краткое описание relate

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

Проверяет, связана ли геометрия поля с геометрией запроса по заданным значениям в шаблоне. Для этого запроса требуется кортеж параметров, (geom, pattern); форма pattern будет зависеть от пространственного бэкенда:

PostGIS и SpatiaLite

В этих пространственных бэкендах шаблон пересечения — строка из девяти символов, определяющих пересечения внутренней, граничной и внешней областей геометрии поля и геометрии запроса. В матрице шаблона пересечения могут использоваться только следующие символы: 1, 2, T, F, или *. Этот тип запроса позволяет пользователям «точно настроить» определённое геометрическое отношение, соответствующее модели DE-9IM. [1]

Пример:

# A tuple lookup parameter is used to specify the geometry and
# the intersection pattern (the pattern here is for 'contains').
Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))

Эквивалент SQL для PostGIS:

SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')

Эквивалент SQL для SpatiaLite:

SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')

Oracle

Здесь шаблон отношения состоит, по крайней мере, из одной из девяти строк отношения: TOUCH, OVERLAPBDYDISJOINT, OVERLAPBDYINTERSECT, EQUAL, INSIDE, COVEREDBY, CONTAINS, COVERS, ON, и ANYINTERACT. Несколько строк могут быть объединены логическим оператором ИЛИ, например, 'inside+touch'. [2] Строки отношения регистронезависимы.

Пример:

Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))

Эквивалент SQL для Oracle:

SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')

Краткое описание touches

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

Проверяет, соприкасается ли геометрия поля с геометрией запроса.

Пример:

Zipcode.objects.filter(poly__touches=geom)

Краткое описание within

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

Проверяет, находится ли геометрия поля внутри геометрии запроса.

Пример:

Zipcode.objects.filter(poly__within=geom)

Краткое описание left

Доступно: PostGIS

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

Пример:

Zipcode.objects.filter(poly__left=geom)

Эквивалент для PostGIS:

SELECT ... WHERE poly << geom

Краткое описание right

Доступно: PostGIS

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

Пример:

Zipcode.objects.filter(poly__right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly >> geom

overlaps_left

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

Проверяет, пересекается ли прямоугольник окружающего поля геометрии или находится слева от прямоугольника окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &< geom

overlaps_right

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

Проверяет, пересекается ли прямоугольник окружающего поля геометрии или находится справа от прямоугольника окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &> geom

overlaps_above

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

Проверяет, пересекается ли прямоугольник окружающего поля геометрии или находится над прямоугольником окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |&> geom

overlaps_below

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

Проверяет, пересекается ли прямоугольник окружающего поля геометрии или находится под прямоугольником окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &<| geom

strictly_above

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

Проверяет, находится ли прямоугольник окружающего поля геометрии строго над прямоугольником окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |>> geom

strictly_below

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

Проверяет, находится ли прямоугольник окружающего поля геометрии строго под прямоугольником окружающего поля геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly <<| geom

Поиск по расстоянию

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

Для получения общего обзора выполнения запросов по расстоянию обратитесь к введению запросов по расстоянию.

Поиск по расстоянию имеет следующий вид:

<field>__<distance lookup>=(<geometry>, <distance value>[, 'spheroid'])

Значение, переданное в поиск по расстоянию, является кортежем; первые два значения являются обязательными и представляют собой геометрию, для которой вычисляются расстояния, и значение расстояния (либо число в единицах поля, либо объект Distance). В каждом поиске по расстоянию, кроме dwithin, может быть включён необязательный третий элемент, 'spheroid', чтобы указать GeoDjango использовать функции вычисления расстояния по эллипсоиду, более точные для полей с геодезической системой координат (например, ST_Distance_Spheroid используется вместо ST_Distance_Sphere). Более простая функция ST_Distance используется с проекционными системами координат.

distance_gt

Возвращает модели, где расстояние до поля геометрии от геометрии поиска больше заданного значения расстояния.

Пример:

Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))

distance_gte

Возвращает модели, где расстояние до поля геометрии от геометрии поиска больше или равно заданному значению расстояния.

Пример:

Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))

distance_lt

Возвращает модели, где расстояние до поля геометрии от геометрии поиска меньше заданного значения расстояния.

Пример:

Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))

distance_lte

Возвращает модели, где расстояние до поля геометрии от геометрии поиска меньше или равно заданному значению расстояния.

Пример:

Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))

dwithin

Возвращает модели, где расстояние до поля геометрии от геометрии поиска находится в заданном расстоянии друг от друга. Обратите внимание, что вы можете указать только объекты Distance, если целевые геометрии находятся в проекционной системе. Для географических геометрий используйте единицы поля геометрии (например, градусы для WGS84) .

Пример:

Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))

GeoQuerySet Методы

Методы GeoQuerySet определяют, что пространственная операция выполняется над каждым пространственным полем геометрии в наборе запросов и сохраняет её вывод в новом атрибуте модели (как правило, с именем метода GeoQuerySet).

Также существуют агрегированные методы GeoQuerySet , которые возвращают единственное значение вместо набора запросов. Этот раздел опишет API и доступность каждого метода GeoQuerySet , доступного в GeoDjango.

За исключением нескольких случаев, следующие ключевые аргументы могут быть использованы со всеми методами GeoQuerySet:

Измерение

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

area

GeoQuerySet.area(**kwargs)

Возвращает площадь поля геометрии в атрибуте area каждого элемента этого GeoQuerySet.

distance

GeoQuerySet.distance(geom, **kwargs)

Этот метод принимает геометрию в качестве параметра и прикрепляет атрибут distance к каждой модели в возвращенном наборе запросов, который содержит расстояние (как объект Distance) до заданной геометрии.

В следующем примере (взятом из тестов GeoDjango по расстоянию), вычисляется расстояние от города Хобарт (Тасмания) до каждой другой PointField в AustraliaCity наборе результатов запроса:

>>> pnt = AustraliaCity.objects.get(name='Hobart').point
>>> for city in AustraliaCity.objects.distance(pnt): print(city.name, city.distance)
Wollongong 990071.220408 m
Shellharbour 972804.613941 m
Thirroul 1002334.36351 m
Mittagong 975691.632637 m
Batemans Bay 834342.185561 m
Canberra 598140.268959 m
Melbourne 575337.765042 m
Sydney 1056978.87363 m
Hobart 0.0 m
Adelaide 1162031.83522 m
Hillsdale 1049200.46122 m

length

GeoQuerySet.length(**kwargs)

Возвращает длину геометрического поля в атрибуте length (объект Distance) каждого объекта модели в наборе результатов запроса.

perimeter

GeoQuerySet.perimeter(**kwargs)

Возвращает периметр геометрического поля в атрибуте perimeter (объект Distance) каждого объекта модели в наборе результатов запроса.

Геометрические отношения

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

centroid

GeoQuerySet.centroid(**kwargs)

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

Возвращает значение centroid для географического поля в атрибуте centroid каждого элемента GeoQuerySet.

envelope

GeoQuerySet.envelope(**kwargs)

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

Возвращает геометрию, представляющую ограничивающую прямоугольную область геометрического поля в атрибуте envelope каждого элемента GeoQuerySet.

point_on_surface

GeoQuerySet.point_on_surface(**kwargs)

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

Возвращает геометрию типа Point, гарантированно расположенную на поверхности геометрического поля в атрибуте point_on_surface каждого элемента набора результатов запроса; в противном случае устанавливает None.

Редактор геометрии

force_rhr

GeoQuerySet.force_rhr(**kwargs)

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

Возвращает изменённую версию многоугольника/многоугольника, в котором все вершины следуют правилу правой руки, и прикрепляет её как атрибут force_rhr к каждому элементу набора результатов запроса.

reverse_geom

GeoQuerySet.reverse_geom(**kwargs)

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

Изменяет порядок координат геометрического поля и прикрепляет его как атрибут reverse к каждому элементу набора результатов запроса.

scale

GeoQuerySet.scale(x, y, z=0.0, **kwargs)

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

snap_to_grid

GeoQuerySet.snap_to_grid(*args, **kwargs)

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

transform

GeoQuerySet.transform(srid=4326, **kwargs)

Метод transform преобразует геометрическое поле модели в систему пространственной привязки, указанную параметром srid. Если параметр srid не указан, по умолчанию используется 4326 (WGS84).

Пример:

>>> qs = Zipcode.objects.all().transform() # Transforms to WGS84
>>> qs = Zipcode.objects.all().transform(32140) # Transforming to "NAD83 / Texas South Central"
>>> print(qs[0].poly.srid)
32140
>>> print(qs[0].poly)
POLYGON ((234055.1698884720099159 4937796.9232223574072123 ...

translate

GeoQuerySet.translate(x, y, z=0.0, **kwargs)

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

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

Операции с геометрией

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

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

difference

GeoQuerySet.difference(geom)

Возвращает пространственную разность географического поля и заданной геометрии в атрибуте difference каждого элемента GeoQuerySet.

intersection

GeoQuerySet.intersection(geom)

Возвращает пространственное пересечение географического поля с заданной геометрией в атрибуте intersection на каждом элементе GeoQuerySet.

sym_difference

GeoQuerySet.sym_difference(geom)

Возвращает симметрическую разность географического поля и заданной геометрии в атрибуте sym_difference на каждом элементе GeoQuerySet.

union

GeoQuerySet.union(geom)

Возвращает объединение географического поля с заданной геометрией в атрибуте union на каждом элементе GeoQuerySet.

Вывод геометрии

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

geohash

GeoQuerySet.geohash(precision=20, **kwargs)

Прикрепляет атрибут geohash к каждой модели набора запросов, содержащий представление геометрии в формате GeoHash.

geojson

GeoQuerySet.geojson(**kwargs)

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

Прикрепляет атрибут geojson к каждой модели в наборе запросов, содержащий представление геометрии в формате GeoJSON.

gml

GeoQuerySet.gml(**kwargs)

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

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

Пример:

>>> qs = Zipcode.objects.all().gml()
>>> print(qs[0].gml)
<gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...  -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>

kml

GeoQuerySet.kml(**kwargs)

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

Прикрепляет атрибут kml к каждой модели в наборе запросов, содержащий представление геометрии в формате языка разметки Keyhole (KML). Следует отметить, что содержимое KML преобразуется в WGS84 при необходимости.

Пример:

>>> qs = Zipcode.objects.all().kml()
>>> print(qs[0].kml)
<Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ... -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>

svg

GeoQuerySet.svg(**kwargs)

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

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

Разное

mem_size

GeoQuerySet.mem_size(**kwargs)

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

Возвращает размер памяти (количество байтов), занимаемый полем геометрии в атрибуте mem_size на каждом элементе GeoQuerySet.

num_geom

GeoQuerySet.num_geom(**kwargs)

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

Возвращает количество геометрий в атрибуте num_geom на каждом элементе GeoQuerySet, если поле геометрии является коллекцией (например, GEOMETRYCOLLECTION или MULTI* поле); в противном случае устанавливает None.

num_points

GeoQuerySet.num_points(**kwargs)

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

Возвращает количество точек в первом полилинии в поле геометрии в атрибуте num_points на каждом элементе GeoQuerySet; в противном случае устанавливает None.

Пространственные агрегаты

Методы агрегации

collect

GeoQuerySet.collect(**kwargs)

Сокращение для aggregate(Collect(<field>)).

extent

GeoQuerySet.extent(**kwargs)

Сокращение для aggregate(Extent(<field>)).

extent3d

GeoQuerySet.extent3d(**kwargs)

Сокращение для aggregate(Extent3D(<field>)).

make_line

GeoQuerySet.make_line(**kwargs)

Сокращение для aggregate(MakeLine(<field>)).

unionagg

GeoQuerySet.unionagg(**kwargs)

Сокращение для aggregate(Union(<field>)).

Функции агрегирования

Django предоставляет некоторые функции агрегирования, специфичные для ГИС. Для получения подробной информации о том, как использовать эти функции агрегирования, см. руководство по темам агрегирования.

Пример:

>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))

Collect

class Collect(geo_field) [source]

Доступность: PostGIS, Spatialite (≥3.0)

Возвращает GEOMETRYCOLLECTION или MULTI геометрический объект из столбца геометрии. Это аналогично упрощенной версии агрегата Union, за исключением того, что он может быть на несколько порядков быстрее, чем выполнение объединения, поскольку он просто объединяет геометрии в коллекцию или многообъект, не заботясь о растворении границ.

Extent

class Extent(geo_field) [source]

Доступность: PostGIS, Oracle, Spatialite (≥3.0)

Возвращает область всех geo_field в QuerySet в виде четвёрки, включающей координаты нижнего левого и верхнего правого углов.

Пример:

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
>>> print(qs['poly__extent'])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)

Extent3D

class Extent3D(geo_field) [source]

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

Возвращает 3D область всех geo_field в QuerySet в виде шестикортежа, включающего координаты нижнего левого и верхнего правого углов (каждая с координатами x, y и z).

Пример:

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly'))
>>> print(qs['poly__extent3d'])
(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)

MakeLine

class MakeLine(geo_field) [source]

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

Возвращает LineString, построенный из геометрий поля точек в QuerySet. В настоящее время сортировка запроса не оказывает влияния.

Пример:

>>> print(City.objects.filter(name__in=('Houston', 'Dallas')
...      ).aggregate(MakeLine('poly'))['poly__makeline']
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)

Union

class Union(geo_field) [source]

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

Этот метод возвращает объект GEOSGeometry, включающий объединение каждой геометрии в наборе запросов. Обратите внимание, что использование Union является ресурсоёмким и может потребовать значительного времени на больших наборах запросов.

Пример:

>>> u = Zipcode.objects.aggregate(Union(poly))  # This may take a long time.
>>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly))  # A more sensible approach.

Примечания