GEOS API

Обзор

Что такое GEOS?

GEOS расшифровывается как Geometry Engine — Open Source и представляет собой библиотеку на C++, адаптированную из Java Topology Suite. GEOS реализует пространственные предикаты и операторы, соответствующие спецификации OpenGIS Simple Features for SQL. GEOS, теперь проект OSGeo, изначально разрабатывался и поддерживался компанией Refractions Research из Виктории, Канада.

Особенности

GeoDjango реализует высокоуровневый Python-обёртку для библиотеки GEOS, её возможности включают:

• Интерфейс с лицензией BSD для геометрических процедур GEOS, реализованный чисто на Python с использованием ctypes.
• Слабая связь с GeoDjango. Например, объекты GEOSGeometry могут использоваться вне проекта/приложения Django. Другими словами, нет необходимости устанавливать DJANGO_SETTINGS_MODULE или использовать базу данных и т. д.
• Изменяемость: объекты GEOSGeometry могут быть изменены.
• Поддержка различных платформ и проверка; совместим с Windows, Linux, Solaris и macOS.

Учебник

Этот раздел содержит краткое введение и учебник по работе с объектами GEOSGeometry.

Создание геометрии

Объекты GEOSGeometry могут быть созданы несколькими способами. Первый способ — просто инициализировать объект на каком-либо пространственном входе — вот примеры создания одной и той же геометрии из WKT, HEX, WKB и GeoJSON:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry("POINT(5 23)")  # WKT
>>> pnt = GEOSGeometry("010100000000000000000014400000000000003740")  # HEX
>>> pnt = GEOSGeometry(
...     memoryview(
...         b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@"
...     )
... )  # WKB
>>> pnt = GEOSGeometry(
...     '{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'
... )  # GeoJSON

Другой вариант — использовать конструктор для конкретного типа геометрии, которую вы хотите создать. Например, объект Point может быть создан путём передачи координат X и Y в его конструктор:

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)

Все эти конструкторы принимают ключевой аргумент srid. Например:

>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry("POINT (0 0)", srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)

Наконец, есть фабричный метод fromfile(), который возвращает объект GEOSGeometry из файла:

>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile("/path/to/pnt.wkt")
>>> pnt = fromfile(open("/path/to/pnt.wkt"))

Геометрии — это элементы Python

Объекты GEOSGeometry являются «элементами Python», другими словами, к компонентам можно получить доступ, изменить и перебрать их с помощью стандартных соглашений Python. Например, вы можете перебрать координаты в объекте Point:

>>> pnt = Point(5, 23)
>>> [coord for coord in pnt]
[5.0, 23.0]

С любым геометрическим объектом свойство GEOSGeometry.coords может использоваться для получения геометрических координат в виде кортежа Python:

>>> pnt.coords
(5.0, 23.0)

Вы можете получить/изменить компоненты геометрии, используя стандартные методы индексирования Python. Однако возвращаемое значение зависит от типа геометрии объекта. Например, индексирование объекта LineString возвращает кортеж координат:

>>> from django.contrib.gis.geos import LineString
>>> line = LineString((0, 0), (0, 50), (50, 50), (50, 0), (0, 0))
>>> line[0]
(0.0, 0.0)
>>> line[-2]
(50.0, 0.0)

А индексирование объекта Polygon вернёт кольцо (объект LinearRing), соответствующее индексу:

>>> from django.contrib.gis.geos import Polygon
>>> poly = Polygon(((0.0, 0.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (0.0, 0.0)))
>>> poly[0]
<LinearRing object at 0x1044395b0>
>>> poly[0][-2]  # second-to-last coordinate of external ring
(50.0, 0.0)

Кроме того, координаты/компоненты геометрии могут быть добавлены или изменены, как и в списке Python:

>>> line[0] = (1.0, 1.0)
>>> line.pop()
(0.0, 0.0)
>>> line.append((1.0, 1.0))
>>> line.coords
((1.0, 1.0), (0.0, 50.0), (50.0, 50.0), (50.0, 0.0), (1.0, 1.0))

Геометрии поддерживают операции множества:

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (2, 2))
>>> ls2 = LineString((1, 1), (3, 3))
>>> print(ls1 | ls2)  # equivalent to `ls1.union(ls2)`
MULTILINESTRING ((0 0, 1 1), (1 1, 2 2), (2 2, 3 3))
>>> print(ls1 & ls2)  # equivalent to `ls1.intersection(ls2)`
LINESTRING (1 1, 2 2)
>>> print(ls1 - ls2)  # equivalent to `ls1.difference(ls2)`
LINESTRING(0 0, 1 1)
>>> print(ls1 ^ ls2)  # equivalent to `ls1.sym_difference(ls2)`
MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))

>>> from django.contrib.gis.geos import LineString
>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((1, 1), (0, 0))
>>> ls3 = LineString((1, 1), (0, 0), srid=4326)
>>> ls1.equals(ls2)
True
>>> ls1 == ls2
False
>>> ls3 == ls2  # different SRIDs
False

Геометрические объекты

GEOSGeometry

class GEOSGeometry(geo_input, srid=None)

Параметры:	geo_input — значение входных данных геометрии (строка или memoryview) srid (int) — идентификатор пространственной системы координат

Это базовый класс для всех геометрических объектов GEOS. Он инициализируется заданным аргументом geo_input, а затем предполагает соответствующий подкласс геометрии (например, GEOSGeometry('POINT(1 1)') создаст объект Point).

Параметр srid, если задан, устанавливается как SRID создаваемой геометрии, если у geo_input нет SRID. Если разные SRID предоставлены через параметры geo_input и srid, то произойдёт исключение ValueError.

>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry("POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=4326;POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=1;POINT EMPTY", srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.

Принимаются следующие форматы ввода с соответствующими типами Python:

Для формата GeoJSON SRID устанавливается на основе члена crs. Если crs не указан, SRID по умолчанию равен 4326.

classmethod GEOSGeometry.from_gml(gml_string)

Создаёт объект GEOSGeometry из данной строки GML.

Свойства

GEOSGeometry.coords

Возвращает координаты геометрии в виде кортежа.

GEOSGeometry.dims

Возвращает размерность геометрии:

• 0 для Point и MultiPoint
• 1 для LineString и MultiLineString
• 2 для Polygon и MultiPolygon
• -1 для пустых GeometryCollection
• максимальная размерность её элементов для непустых GeometryCollection

GEOSGeometry.empty

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

GEOSGeometry.geom_type

Возвращает строку, соответствующую типу геометрии. Например:

>>> pnt = GEOSGeometry("POINT(5 23)")
>>> pnt.geom_type
'Point'

GEOSGeometry.geom_typeid

Возвращает идентификационный номер типа геометрии GEOS. В следующей таблице показано значение для каждого типа геометрии:

Геометрия	ID
Point	0
LineString	1
LinearRing	2
Polygon	3
MultiPoint	4
MultiLineString	5
MultiPolygon	6
GeometryCollection	7

GEOSGeometry.num_coords

Возвращает количество координат в геометрии.

GEOSGeometry.num_geom

Возвращает количество геометрий в этой геометрии. Другими словами, вернет 1 для всех, кроме коллекций геометрий.

GEOSGeometry.hasz

Возвращает булево значение, указывающее, является ли геометрия трехмерной.

GEOSGeometry.ring

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

GEOSGeometry.simple

Возвращает булево значение, указывающее, является ли геометрия «простой». Геометрия простая тогда и только тогда, когда она не пересекает себя (кроме точек границы). Например, объект LineString не прост, если он пересекает себя. Таким образом, объекты LinearRing и Polygon всегда просты, поскольку по определению они не могут пересекать сами себя.

GEOSGeometry.valid

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

GEOSGeometry.valid_reason

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

GEOSGeometry.srid

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

>>> pnt = Point(5, 23)
>>> print(pnt.srid)
None
>>> pnt.srid = 4326
>>> pnt.srid
4326

Свойства вывода

Свойства в этом разделе экспортируют объект GEOSGeometry в другой формат. Этот вывод может быть в виде строки, буфера или даже другого объекта.

GEOSGeometry.ewkt

Возвращает «расширенный» текст Well-Known (EWKT) геометрии. Это представление специфично для PostGIS и является надмножеством стандарта OGC WKT. [1] По существу, SRID предваряет представление WKT, например SRID=4326;POINT(5 23).

Примечание

Вывод из этого свойства не включает информацию 3dm, 3dz и 4d, которую PostGIS поддерживает в своих представлениях EWKT.

GEOSGeometry.hex

Возвращает WKB этой геометрии в шестнадцатеричном формате. Обратите внимание, что значение SRID не включено в это представление, поскольку оно не является частью спецификации OGC (используйте свойство GEOSGeometry.hexewkb вместо этого).

GEOSGeometry.hexewkb

Возвращает EWKB этой геометрии в шестнадцатеричном формате. Это расширение спецификации WKB, которое включает значение SRID, являющееся частью этой геометрии.

GEOSGeometry.json

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

GEOSGeometry.geojson

Псевдоним для GEOSGeometry.json.

GEOSGeometry.kml

Возвращает представление геометрии в формате KML (Keyhole Markup Language). Это следует использовать только для геометрий с SRID 4326 (WGS84), но это ограничение не проверяется.

GEOSGeometry.ogr

Возвращает объект OGRGeometry, соответствующий геометрии GEOS.

GEOSGeometry.wkb

Возвращает представление геометрии в формате WKB (Well-Known Binary) в виде Python-буфера. Значение SRID не включено, используйте свойство GEOSGeometry.ewkb вместо этого.

GEOSGeometry.ewkb

Возвращает представление EWKB этой геометрии как Python-буфер. Это расширение спецификации WKB, которое включает любое значение SRID, являющееся частью этой геометрии.

GEOSGeometry.wkt

Возвращает текст Well-Known (WKT) геометрии (стандарт OGC).

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

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

GEOSGeometry.contains(other)

Возвращает True если other.within(this) возвращает True.

GEOSGeometry.covers(other)

Возвращает True если эта геометрия охватывает указанную геометрию.

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

• Каждая точка другой геометрии является точкой этой геометрии.
• Матрица пересечения DE-9IM для двух геометрий равна T*****FF*, *T****FF*, ***T**FF*, или ****T*FF*.

Если хотя бы одна из геометрий пуста, возвращает False.

Этот предикат похож на GEOSGeometry.contains(), но более инклюзивен (т.е. возвращает True для большего количества случаев). В частности, в отличие от contains(), он не различает точки на границе и внутри геометрий. Для большинства случаев covers() предпочтительнее contains(). Кроме того, covers() более пригоден для оптимизации и, следовательно, должен превосходить contains().

GEOSGeometry.crosses(other)

Возвращает True если матрица пересечения DE-9IM для двух геометрий равна T*T****** (для точки и кривой, точки и области или линии и области) 0******** (для двух кривых).

GEOSGeometry.disjoint(other)

Возвращает True если матрица пересечения DE-9IM для двух геометрий равна FF*FF****.

GEOSGeometry.equals(other)

Возвращает True если матрица пересечения DE-9IM для двух геометрий равна T*F**FFF*.

GEOSGeometry.equals_exact(other, tolerance=0)

Возвращает true, если две геометрии точно равны с заданной точностью. Значение tolerance должно быть числом с плавающей точкой, представляющим толерантность погрешности в сравнении, например, poly1.equals_exact(poly2, 0.001) сравнивает равенство с точностью до одной тысячной единицы.

GEOSGeometry.intersects(other)

Возвращает True если GEOSGeometry.disjoint() равно False.

GEOSGeometry.overlaps(other)

Возвращает true, если матрица пересечения DE-9IM для двух геометрий равна T*T***T** (для двух точек или двух поверхностей) 1*T***T** (для двух кривых).

GEOSGeometry.relate_pattern(other, pattern)

Возвращает True если элементы в матрице пересечения DE-9IM для этой геометрии и другой совпадают с заданным шаблоном pattern — строкой из девяти символов алфавита: {T, F, *, 0}.

GEOSGeometry.touches(other)

Возвращает True если матрица пересечения DE-9IM для двух геометрий равна FT*******, F**T***** или F***T****.

GEOSGeometry.within(other)

Возвращает True если матрица пересечения DE-9IM для двух геометрий равна T*F**F***.

Топологические методы

GEOSGeometry.buffer(width, quadsegs=8)

Возвращает GEOSGeometry, представляющий все точки, расстояние от которых до данной геометрии меньше или равно заданному width. Необязательный параметр quadsegs устанавливает количество сегментов, используемых для приближения четверти окружности (по умолчанию 8).

GEOSGeometry.buffer_with_style(width, quadsegs=8, end_cap_style=1, join_style=1, mitre_limit=5.0)

Аналогично buffer(), но позволяет настраивать стиль буфера.

• end_cap_style может быть круговой (1), плоской (2) или квадратной (3).
• join_style может быть круговой (1), скошенной (2) или фаской (3).
• Предел отношения скоса (mitre_limit) влияет только на стиль скошенного соединения.

GEOSGeometry.difference(other)

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

GEOSGeometry.interpolate(distance)

GEOSGeometry.interpolate_normalized(distance)

При заданном расстоянии (float), возвращает точку (или ближайшую точку) внутри геометрии (LineString или MultiLineString) на этом расстоянии. Нормализованная версия принимает расстояние как число с плавающей точкой между 0 (начало) и 1 (конец).

Обратное преобразование GEOSGeometry.project().

GEOSGeometry.intersection(other)

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

GEOSGeometry.project(point)

GEOSGeometry.project_normalized(point)

Возвращает расстояние (число с плавающей точкой) от начала геометрии (LineString или MultiLineString) до точки, спроецированной на геометрию (то есть до точки линии, ближайшей к заданной точке). Нормализованная версия возвращает расстояние как число с плавающей точкой между 0 (начало) и 1 (конец).

Обратное преобразование GEOSGeometry.interpolate().

GEOSGeometry.relate(other)

Возвращает матрицу пересечения DE-9IM (строка), представляющую топологические отношения между этой геометрией и другой.

GEOSGeometry.simplify(tolerance=0.0, preserve_topology=False)

Возвращает новую GEOSGeometry, упрощенную до заданной толерантности с использованием алгоритма Дугласа-Пекера. Более высокое значение толерантности подразумевает меньшее количество точек на выходе. Если толерантность не указана, она по умолчанию равна 0.

По умолчанию эта функция не сохраняет топологию. Например, объекты Polygon могут быть разделены, сведены к линиям или исчезнуть. Polygon дыры могут быть созданы или исчезнуть, а линии могут пересекаться. Указав preserve_topology=True, результат будет иметь такую же размерность и количество компонентов, как входной; однако это значительно медленнее.

GEOSGeometry.sym_difference(other)

Возвращает GEOSGeometry, объединяющий точки этой геометрии, не входящие в другую, и точки другой, не входящие в эту геометрию.

GEOSGeometry.union(other)

Возвращает GEOSGeometry, представляющий все точки в этой геометрии и другой.

Топологические свойства

GEOSGeometry.boundary

Возвращает границу как новый объект геометрии.

GEOSGeometry.centroid

Возвращает объект Point, представляющий геометрический центр геометрии. Точка не гарантируется, что будет находиться внутри геометрии.

GEOSGeometry.convex_hull

Возвращает наименьший Polygon, содержащий все точки в геометрии.

GEOSGeometry.envelope

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

GEOSGeometry.point_on_surface

Вычисляет и возвращает Point, гарантированно находящийся внутри этой геометрии.

GEOSGeometry.unary_union

Вычисляет объединение всех элементов этой геометрии.

Результат подчиняется следующему соглашению:

• Объединение набора LineString имеет эффект полного соединения и растворения линий.
• Объединение набора Polygon всегда вернёт геометрию Polygon или MultiPolygon (в отличие от GEOSGeometry.union(), который может вернуть геометрии меньшей размерности, если произойдёт сбой топологии).

Другие свойства и методы

GEOSGeometry.area

Это свойство возвращает площадь геометрии.

GEOSGeometry.extent

Это свойство возвращает область определения этой геометрии в виде 4-кортежа, состоящего из (xmin, ymin, xmax, ymax).

GEOSGeometry.clone()

Этот метод возвращает GEOSGeometry, являющийся клоном оригинала.

GEOSGeometry.distance(geom)

Возвращает расстояние между ближайшими точками этой геометрии и заданной geom (другой объект GEOSGeometry).

Примечание

Расчёты расстояния GEOS линейные – другими словами, GEOS не выполняет сферический расчёт, даже если SRID указывает географическую систему координат.

GEOSGeometry.length

Возвращает длину этой геометрии (например, 0 для Point, длину LineString или окружность Polygon).

GEOSGeometry.prepared

Возвращает GEOS PreparedGeometry для содержимого этой геометрии. PreparedGeometry объекты оптимизированы для операций содержит, пересекается, покрывает, пересекает, не пересекается, перекрывается, касается и находится внутри. Обратитесь к документации Prepared Geometries для получения дополнительной информации.

GEOSGeometry.srs

Возвращает объект SpatialReference, соответствующий SRID геометрии или None.

GEOSGeometry.transform(ct, clone=False)

Преобразует геометрию в соответствии с заданным параметром преобразования координат (ct), который может быть целым SRID, строкой WKT пространственной ссылки, строкой PROJ, объектом SpatialReference или объектом CoordTransform. По умолчанию геометрия преобразуется на месте, и ничего не возвращается. Однако если параметр clone установлен, то геометрия не изменяется, и вместо этого возвращается преобразованный клон геометрии.

Примечание

Возбуждает GEOSException, если GDAL недоступен или SRID геометрии None или меньше 0. Не накладывает никаких ограничений на SRID геометрии, если вызывается с объектом CoordTransform.

GEOSGeometry.make_valid()

Новое в Django 4.1.

Возвращает эквивалентную корректную GEOSGeometry, пытаясь не потерять ни одного из входных вершин. Если геометрия уже корректна, она возвращается без изменений. Аналогично функции базы данных MakeValid. Требуется GEOS 3.8.

GEOSGeometry.normalize(clone=False)

Преобразует эту геометрию в каноническую форму. Если параметр clone установлен, то геометрия не изменяется, и вместо этого возвращается нормализованный клон геометрии:

>>> g = MultiPoint(Point(0, 0), Point(2, 2), Point(1, 1))
>>> print(g)
MULTIPOINT (0 0, 2 2, 1 1)
>>> g.normalize()
>>> print(g)
MULTIPOINT (2 2, 1 1, 0 0)

Изменено в Django 4.1:

Добавлен аргумент clone.

Точка

class Point(x=None, y=None, z=None, srid=None)

Объекты Point создаются, используя аргументы, представляющие координаты компоненты точки или с использованием единственной последовательности координат. Например, следующие эквивалентны:

>>> pnt = Point(5, 23)
>>> pnt = Point([5, 23])

Пустые объекты Point могут быть созданы, передавая не аргументы или пустую последовательность. Следующие эквивалентны:

>>> pnt = Point()
>>> pnt = Point([])

Линия

class LineString(*args, **kwargs)

Объекты LineString создаются, используя аргументы, которые являются либо последовательностью координат, либо объектами Point. Например, следующие эквивалентны:

>>> ls = LineString((0, 0), (1, 1))
>>> ls = LineString(Point(0, 0), Point(1, 1))

Кроме того, объекты LineString также могут быть созданы, передавая одну последовательность координат или объектов Point:

>>> ls = LineString(((0, 0), (1, 1)))
>>> ls = LineString([Point(0, 0), Point(1, 1)])

Пустые объекты LineString могут быть созданы, передавая не аргументы или пустую последовательность. Следующие эквивалентны:

>>> ls = LineString()
>>> ls = LineString([])

closed

Возвращает, замкнута ли эта LineString.

Линейная линия

class LinearRing(*args, **kwargs)

Объекты LinearRing создаются точно так же, как объекты LineString, однако координаты должны быть замкнутыми, то есть первая координата должна быть такой же, как последняя. Например:

>>> ls = LinearRing((0, 0), (0, 1), (1, 1), (0, 0))

Обратите внимание, что (0, 0) является первой и последней координатой – если они не были равны, было бы вызвано исключение.

is_counterclockwise

Возвращает, является ли эта LinearRing против часовой стрелки.

Многоугольник

class Polygon(*args, **kwargs)

Объекты Polygon могут быть созданы, передавая параметры, представляющие кольца многоугольника. Параметры должны быть экземплярами LinearRing или последовательностью, которая может быть использована для построения LinearRing:

>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
>>> poly = Polygon(ext_coords, int_coords)
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))

classmethod from_bbox(bbox)

Возвращает объект многоугольника из заданной области определения, 4-кортежа, состоящего из (xmin, ymin, xmax, ymax).

num_interior_rings

Возвращает количество внутренних колец в этой геометрии.

>>> if poly_1.area > poly_2.area:
...     pass
...

Коллекции геометрий

Многоточечная

class MultiPoint(*args, **kwargs)

Объекты MultiPoint можно создать, передавая в качестве аргументов объекты Point, или последовательность объектов Point:

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint((Point(0, 0), Point(1, 1)))

MultiLineString

class MultiLineString(*args, **kwargs)

Объекты MultiLineString можно создать, передавая в качестве аргументов объекты LineString, или последовательность объектов LineString:

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

merged

Возвращает LineString, представляющий собой объединённую линию всех компонентов в этом MultiLineString.

closed

Возвращает True только тогда, когда все элементы замкнуты.

MultiPolygon

class MultiPolygon(*args, **kwargs)

Объекты MultiPolygon можно создать, передавая объекты Polygon, или последовательность объектов Polygon:

>>> p1 = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> p2 = Polygon(((1, 1), (1, 2), (2, 2), (1, 1)))
>>> mp = MultiPolygon(p1, p2)
>>> mp = MultiPolygon([p1, p2])

GeometryCollection

class GeometryCollection(*args, **kwargs)

Объекты GeometryCollection можно создать, передавая другие объекты GEOSGeometry, или последовательность объектов GEOSGeometry:

>>> poly = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))

Подготовленные геометрии

Для получения подготовленной геометрии обратитесь к свойству GEOSGeometry.prepared. После получения экземпляра PreparedGeometry можно использовать его методы пространственных предикатов, перечисленных ниже, с другими объектами GEOSGeometry. Операция с подготовленной геометрией может быть на порядки быстрее — чем сложнее подготовленная геометрия, тем больше ускорение при выполнении операции. Более подробную информацию вы можете найти на странице вики GEOS по подготовленным геометриям GEOS wiki page on prepared geometries.

Например:

>>> from django.contrib.gis.geos import Point, Polygon
>>> poly = Polygon.from_bbox((0, 0, 5, 5))
>>> prep_poly = poly.prepared
>>> prep_poly.contains(Point(2.5, 2.5))
True

PreparedGeometry

class PreparedGeometry

Все методы PreparedGeometry принимают аргумент other, который должен быть экземпляром GEOSGeometry.

contains(other)

contains_properly(other)

covers(other)

crosses(other)

disjoint(other)

intersects(other)

overlaps(other)

touches(other)

within(other)

Геометрии-фабрики

fromfile(file_h)

Параметры:	file_h (объект Python file или путь к файлу) – входной файл, содержащий пространственные данные
Тип возвращаемого значения:	объект GEOSGeometry, соответствующий пространственным данным в файле

Пример:

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile("/home/bob/geom.wkt")

fromstr(string, srid=None)

Параметры:	string (str) – строка, содержащая пространственные данные srid (int) – идентификатор пространственной системы координат
Тип возвращаемого значения:	объект GEOSGeometry, соответствующий пространственным данным в строке

fromstr(string, srid) эквивалентен GEOSGeometry(string, srid).

Пример:

>>> from django.contrib.gis.geos import fromstr
>>> pnt = fromstr("POINT(-90.5 29.5)", srid=4326)

Объекты ввода/вывода

Объекты чтения

Классы ввода/вывода для чтения возвращают экземпляр GEOSGeometry из входных данных WKB и/или WKT, переданных методу read(geom).

class WKBReader

Пример:

>>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader()
>>> wkb_r.read("0101000000000000000000F03F000000000000F03F")
<Point object at 0x103a88910>

class WKTReader

Пример:

>>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader()
>>> wkt_r.read("POINT(1 1)")
<Point object at 0x103a88b50>

Объекты записи

Все объекты записи имеют метод write(geom), который возвращает WKB или WKT заданной геометрии. Кроме того, объекты WKBWriter также имеют свойства, которые можно использовать для изменения порядка байтов и/или включения значения SRID (то есть EWKB).

class WKBWriter(dim=2)

WKBWriter обеспечивает наибольший контроль над выводом. По умолчанию он возвращает WKB, соответствующий OGC, когда вызывается метод write. Однако, он имеет свойства, позволяющие создавать EWKB, расширение WKB-стандарта, включающее дополнительную информацию. Для получения более подробной информации о параметре dim обратитесь к документации WKBWriter.outdim.

write(geom)

Возвращает WKB заданной геометрии как объект Python buffer. Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>

write_hex(geom)

Возвращает WKB геометрии в шестнадцатеричном формате. Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'

byteorder

Это свойство можно установить для изменения порядка байтов представления геометрии.

Значение byteorder	Описание
0	Big Endian (например, совместимо с RISC-системами)
1	Little Endian (например, совместимо с x86-системами)

Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1)
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.byteorder = 0
'00000000013FF00000000000003FF0000000000000'

outdim

Это свойство можно установить для изменения выходной размерности представления геометрии. Другими словами, если у вас есть 3D-геометрия, установите её в 3, чтобы значение Z было включено в WKB.

Значение outdim	Описание
2	По умолчанию, вывод 2D WKB.
3	Вывод 3D WKB.

Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> wkb_w.outdim
2
>>> pnt = Point(1, 1, 1)
>>> wkb_w.write_hex(pnt)  # By default, no Z value included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.outdim = 3  # Tell writer to include Z values
>>> wkb_w.write_hex(pnt)
'0101000080000000000000F03F000000000000F03F000000000000F03F'

srid

Установите это свойство с булевым значением, чтобы указать, нужно ли включать SRID геометрии в представление WKB. Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> wkb_w = WKBWriter()
>>> pnt = Point(1, 1, srid=4326)
>>> wkb_w.write_hex(pnt)  # By default, no SRID included:
'0101000000000000000000F03F000000000000F03F'
>>> wkb_w.srid = True  # Tell writer to include SRID
>>> wkb_w.write_hex(pnt)
'0101000020E6100000000000000000F03F000000000000F03F'

class WKTWriter(dim=2, trim=False, precision=None)

Этот класс позволяет выводить представление WKT геометрии. См. атрибуты WKBWriter.outdim, trim и precision для получения подробной информации об аргументах конструктора.

write(geom)

Возвращает WKT заданной геометрии. Пример:

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'

outdim

См. WKBWriter.outdim.

trim

Это свойство используется для включения или отключения обрезки ненужных десятичных знаков.

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1, 1)
>>> wkt_w = WKTWriter()
>>> wkt_w.trim
False
>>> wkt_w.write(pnt)
'POINT (1.0000000000000000 1.0000000000000000)'
>>> wkt_w.trim = True
>>> wkt_w.write(pnt)
'POINT (1 1)'

precision

Это свойство контролирует точность округления координат; если установлено значение None, округление отключено.

>>> from django.contrib.gis.geos import Point, WKTWriter
>>> pnt = Point(1.44, 1.66)
>>> wkt_w = WKTWriter()
>>> print(wkt_w.precision)
None
>>> wkt_w.write(pnt)
'POINT (1.4399999999999999 1.6599999999999999)'
>>> wkt_w.precision = 0
>>> wkt_w.write(pnt)
'POINT (1 2)'
>>> wkt_w.precision = 1
>>> wkt_w.write(pnt)
'POINT (1.4 1.7)'

Сноски

Настройки

GEOS_LIBRARY_PATH

Строка, указывающая расположение библиотеки GEOS C. Обычно эта настройка используется только в случае, если библиотека GEOS C находится в нестандартном расположении (например, /home/bob/lib/libgeos_c.so).

Исключения

exception GEOSException

Базовое исключение GEOS, указывающее на ошибку, связанную с GEOS.