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 являются объектами 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 – значение ввода геометрии (строка или буфер) 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)

Добавлена в Django 1.11.

Создаёт объект 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 Text (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.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) до точки, спроецированной на геометрию (то есть до точки на линии, ближайшей к заданной точке). Нормализованная версия возвращает расстояние как float между 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) — это первая и последняя координата — если они не равны, будет выведено сообщение об ошибке.

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

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

Значение порядка байтов	Описание
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, чтобы значение 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.