GEOS API

Справочная информация

Что такое ГЕОС?

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() factory, который возвращает объект 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))

Оператор равенства не проверяет пространственное равенство

Оператор равенства GEOSGeometry использует equals_exact(), а не equals(), т.е. он требует, чтобы сравниваемые геометрии имели одинаковые координаты в одинаковых позициях с одинаковыми SRID:

>>> 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. Если через параметры geo_input и srid заданы разные 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:

Формат Тип входа
WKT / EWKT str
HEX / HEXEWKB str
WKB / EWKB buffer
GeoJSON str

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

classmethod GEOSGeometry.from_gml(gml_string)

Конструирует GEOSGeometry из заданной строки GML.

Свойства

GEOSGeometry.coords

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

GEOSGeometry.dims

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

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

Возвращает известный текст геометрии (стандарт 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) на этом расстоянии. Нормализованная версия принимает расстояние в виде float между 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

Возвращает границу в виде нового выделенного объекта Geometry.

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.4, объектом SpatialReference или объектом CoordTransform. По умолчанию геометрия преобразуется на месте и ничего не возвращается. Однако если установлено ключевое слово clone, то геометрия не изменяется, а вместо нее возвращается преобразованный клон геометрии.

Примечание

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

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

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

LinearRing

class LinearRing(*args, **kwargs)

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

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

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

is_counterclockwise
New in Django 3.1.

Возвращает, является ли данный 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

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

Сравнение многоугольников

Обратите внимание, что можно напрямую сравнивать Polygon объекты с < или >, но поскольку сравнение производится через LineString Polygon, это мало что значит (но зато последовательно и быстро). Вы всегда можете принудительно выполнить сравнение с помощью свойства area:

>>> 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. Операция с подготовленной геометрией может быть на порядки быстрее - чем сложнее подготовленная геометрия, тем больше ускорение операции. Для получения дополнительной информации обратитесь к 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 (a Python file object or a string path to the file) – входной файл, содержащий пространственные данные
Тип результата:a GEOSGeometry, соответствующий пространственным данным в файле

Пример:

>>> from django.contrib.gis.geos import fromfile
>>> g = fromfile('/home/bob/geom.wkt')
fromstr(string, srid=None)
Параметры:
  • string (str) – строка, содержащая пространственные данные
  • srid (int) – идентификатор пространственной ссылки
Тип результата:

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

Объекты писателя

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

class WKBWriter(dim=2)

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

Это свойство может быть установлено для изменения выходной размерности представления геометрии. Другими словами, если у вас трехмерная геометрия, установите значение 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)'

Сноски

[1]Смотрите PostGIS EWKB, EWKT and Canonical Forms, документацию PostGIS в гл. 4.1.2.

Настройки

GEOS_LIBRARY_PATH

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

Примечание

В качестве параметра должен быть указан полный путь к общей библиотеке C; другими словами, вы хотите использовать libgeos_c.so, а не libgeos.so.

Исключения

exception GEOSException

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

Вернуться на верх