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

Геометрии являются питоновскими

Объекты GEOSGeometry являются «питоновскими», другими словами, к компонентам можно получить доступ, изменить их и выполнить итерацию по ним, используя стандартные соглашения 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.equals_identical(other)

Новое в Django 5.0.

Возвращает True если две геометрии тождественно эквивалентны, проверяя, что структура, порядок и значения всех вершин идентичны во всех измерениях. NaN значения считаются равными другим NaN значениям. Требуется GEOS 3.12.

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)

При заданном расстоянии (число с плавающей точкой) возвращает точку (или ближайшую точку) внутри геометрии (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 объекты оптимизированы для операций contains, intersects, covers, crosses, disjoint, overlaps, touches и within. Подробную информацию см. в документации по Подготовленным геометриям.

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

Возвращает эквивалентную корректную 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)

Point

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

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

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

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

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

LineString

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

Возвращает значение true или false в зависимости от того, является ли эта LineString замкнутой.

LinearRing

class LinearRing(*args, **kwargs)

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

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

Обратите внимание, что (0, 0) – первая и последняя координаты. Если они не равны, будет выведено сообщение об ошибке.

is_counterclockwise

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

Polygon

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

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

MultiPoint

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 объектами. Операция с подготовленной геометрией может быть на порядки быстрее — чем сложнее подготовленная геометрия, тем больше ускорение при выполнении операции. Для получения дополнительной информации обратитесь к странице wiki GEOS о подготовленных геометриях.

Например:

>>> 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 предоставляет максимальный контроль над выводом. По умолчанию, при вызове метода write, он возвращает WKB, соответствующий OGC. Однако, у него есть свойства, которые позволяют создавать 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.