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

Геометрии являются Pythonic

Объекты 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).

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

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 (Extended Well-Known Binary) в виде Python-буфера. Это расширение спецификации WKB, которое включает любое значение SRID, относящееся к этой геометрии.

GEOSGeometry.wkt

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

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

Незначительные нули удаляются из вывода.

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

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

GEOSGeometry.contains(other)

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

GEOSGeometry.covers(other)

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

Возвращает 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)

При заданном расстоянии (число с плавающей точкой) возвращает точку (или ближайшую точку) внутри геометрии (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

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

GEOSGeometry.centroid

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

GEOSGeometry.convex_hull

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

GEOSGeometry.envelope

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

GEOSGeometry.point_on_surface

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

GEOSGeometry.unary_union

Новое в Django 1.10.

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

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

• Объединение набора 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.

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

В предыдущих версиях требовалось, чтобы 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([])

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

В предыдущих версиях пустой 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([])

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

В предыдущих версиях пустой LineString нельзя было создать.

closed

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

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

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

В предыдущих версиях пустой Polygon нельзя было создать.

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

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

В предыдущих версиях пустой MultiPoint нельзя было создать.

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

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

В предыдущих версиях пустой MultiLineString нельзя было создать.

merged

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

closed

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

Возвращает 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])

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

В предыдущих версиях пустой MultiPolygon не мог быть создан.

cascaded_union

Устарело начиная с версии 1.10: Используйте свойство GEOSGeometry.unary_union вместо этого.

Возвращает Polygon, который является объединением всех полигонов-компонентов в этом наборе. Используемый алгоритм значительно эффективнее (быстрее), чем объединение геометрий по отдельности. [2]

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

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

В предыдущих версиях пустой GeometryCollection не мог быть создан.

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

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

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

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

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

Добавлена возможность передачи параметров dim, 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

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

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

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

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

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