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

class GeoQuerySet(model=None)

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

Так же, как при использовании API наборов запросов, взаимодействие с GeoQuerySet происходит путём цепочки фильтров. Вместо обычных Django полей запросов в этом разделе доступны пространственные запросы для GeometryField.

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

bbcontains

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

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

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

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

Проверяет, перекрываются ли ограничивающие рамки (bounding boxes) геометрического поля и геометрии поиска.

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

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

Проверяет, полностью ли ограничивающая рамка (bounding box) геометрического поля содержится в ограничивающей рамке (bounding box) геометрии поиска.

Пример:

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

exact, 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

Проверяет, находится ли ограничивающая рамка (bounding box) геометрического поля строго слева от ограничивающей рамки (bounding box) геометрии поиска.

Пример:

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).

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_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)

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

Метод 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 к каждой модели в наборе результатов запроса, содержащий представление геометрии в формате Geographic Markup Language (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 Markup Language (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 к каждой модели в наборе результатов запроса, содержащий данные пути в формате Scalable Vector Graphics (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)

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

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

Extent

class Extent(geo_field)

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

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

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

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

Примечания