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(buffer('\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@'))
>>> 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 являются «pythonic», другими словами, компоненты могут быть обработаны, изменены и проитерированы по стандартным правилам 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 – Значение входных данных геометрии (строка или буфер) 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

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

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, представляющий геометрию. Это представление специфично для 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 геометрии (стандарт 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)

Возвращает расстояние (float) от начала геометрии (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. При вызове с объектом CoordTransform никаких ограничений на SRID геометрии не накладывается.

GEOSGeometry.normalize()

Преобразует эту геометрию в каноническую форму:

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

Новое в Django 3.1.

Возвращает 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 только тогда, когда все элементы замкнуты. Требуется GEOS 3.5.

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 обеспечивает наибольший контроль над выводом. По умолчанию он возвращает WKB, совместимый с OGC, когда вызывается метод write. Однако он имеет свойства, позволяющие создавать EWKB — надмножество стандарта WKB, включающее дополнительную информацию. См. документацию по аргументу WKBWriter.outdim для получения дополнительной информации об аргументе dim.

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

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

Значение порядка байтов	Описание
0	Большой порядок байтов (например, совместим с RISC-системами)
1	Малый порядок байтов (например, совместим с 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, чтобы в WKB был включён Z-координата.

Значение 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)'

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

Это свойство управляет точностью округления координат; если значение равно 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.