Справочник API набора запросов GIS

Пространственные поиски

В этом разделе доступны пространственные поиски для GeometryField и RasterField.

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

Поиски с растровыми данными

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

Базовые операторы, используемые в запросах, можно разделить на три категории:

• Прямая поддержка растровых данных N: оператор напрямую принимает растровые данные с обеих сторон поиска, а растровые данные могут быть смешаны с геометрическими.
• Взаимная поддержка растровых данных B: оператор поддерживает растровые данные только если обе стороны поиска получают растровые данные. Растровые данные автоматически преобразуются в геометрию для смешанных поисков.
• Поддержка преобразования геометрии C. У поиска нет прямой поддержки растровых данных, все растровые данные автоматически преобразуются в геометрию.

Ниже приведены примеры SQL-эквивалентов поисков в различных типах поддержки растровых данных. Такая же схема применяется ко всем пространственным поискам.

Пространственные поиски с растровыми данными поддерживаются только для бэкендов PostGIS (обозначенных как PGRaster в этом разделе).

bbcontains

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

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

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

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

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

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

Пример:

Zipcode.objects.filter(poly__contained=geom)

contains

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимная поддержка)

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

Пример:

Zipcode.objects.filter(poly__contains=geom)

contains_properly

Доступность: PostGIS, PGRaster (Взаимная поддержка)

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

Пример:

Zipcode.objects.filter(poly__contains_properly=geom)

coveredby

Доступность: PostGIS, Oracle, PGRaster (Взаимная поддержка), SpatiaLite

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

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

covers

Доступность: PostGIS, Oracle, PGRaster (Взаимная поддержка), SpatiaLite

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

Пример:

Zipcode.objects.filter(poly__covers=geom)

crosses

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__crosses=geom)

disjoint

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимная поддержка)

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

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

equals

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__equals=geom)

exact, same_as

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

Проверяет, соответствует ли геометрическое поле геометрии поиска. В Oracle, MySQL и SpatiaLite проверяется пространственное равенство, в то время как в PostGIS проверяется равенство ограничивающих прямоугольников.

Пример:

Zipcode.objects.filter(poly=geom)

intersects

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

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

Пример:

Zipcode.objects.filter(poly__intersects=geom)

isvalid

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

Проверяет, является ли геометрия допустимой.

Пример:

Zipcode.objects.filter(poly__isvalid=True)

overlaps

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

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

relate

Доступность: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (Преобразование)

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

MariaDB, 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 и MariaDB:

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

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

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

Пример растра:

Zipcode.objects.filter(poly__relate=(rast, 1, 'T*T***FF*'))
Zipcode.objects.filter(rast__2__relate=(rast, 1, 'T*T***FF*'))

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

SELECT ... WHERE ST_Relate(poly, ST_Polygon(rast, 1), 'T*T***FF*')
SELECT ... WHERE ST_Relate(ST_Polygon(rast, 2), ST_Polygon(rast, 1), '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, MariaDB, MySQL, SpatiaLite

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

within

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

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

Пример:

Zipcode.objects.filter(poly__within=geom)

left

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__left=geom)

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

SELECT ... WHERE poly << geom

right

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__right=geom)

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

SELECT ... WHERE poly >> geom

overlaps_left

Доступность: PostGIS, PGRaster (Взаимно)

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

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

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

SELECT ... WHERE poly &< geom

overlaps_right

Доступность: PostGIS, PGRaster (Взаимно)

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

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

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

SELECT ... WHERE poly &> geom

overlaps_above

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

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

SELECT ... WHERE poly |&> geom

overlaps_below

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

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

SELECT ... WHERE poly &<| geom

strictly_above

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

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

SELECT ... WHERE poly |>> geom

strictly_below

Доступность: PostGIS, PGRaster (Преобразование)

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

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

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

SELECT ... WHERE poly <<| geom

Поиск расстояний

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Native)

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

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

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

Значение, переданное в запрос по расстоянию, представляет собой кортеж; первые два значения обязательны и представляют собой геометрию для расчета расстояний и значение расстояния (либо число в единицах поля, объект Distance, либо выражение запроса выражение запроса). Для передачи индекса полосы в запрос используйте 3-кортеж, где второе значение — индекс полосы.

При каждом запросе по расстоянию, кроме dwithin, может быть включен необязательный элемент 'spheroid', чтобы использовать функции расчета расстояния по сфероиду с большей точностью для полей с геодезической системой координат.

В PostgreSQL опция 'spheroid' использует ST_DistanceSpheroid вместо ST_DistanceSphere. Более простая функция 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)))

Функции агрегации

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

Пример:

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

Collect

class Collect(geo_field)

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

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

Extent

class Extent(geo_field)

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

Возвращает область всех 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

Возвращает трехмерную область всех 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, SpatiaLite

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

Пример:

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly'))
>>> print(qs['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.

Примечания