API GEOS

Что такое GEOS?

GEOS расшифровывается как Geometry Engine - Open Source и представляет собой библиотеку C++, портированную из Java Topology Suite. GEOS реализует пространственные предикатные функции и пространственные операторы OpenGIS Simple Features for SQL. В настоящее время GEOS является проектом OSGeo; изначально он был разработан и поддерживался компанией Refractions Research из Виктории, Канада.

Возможности

GeoDjango реализует высокоуровневую оболочку Python для библиотеки GEOS. К её возможностям относятся:

• Интерфейс к геометрическим функциям GEOS с лицензией BSD, полностью реализованный на Python с использованием ctypes.
• Слабая зависимость от GeoDjango. Например, объекты GEOSGeometry можно использовать вне проекта или приложения Django. Другими словами, не требуется задавать DJANGO_SETTINGS_MODULE или использовать базу данных и т. д.
• Изменяемость: объекты GEOSGeometry можно изменять.
• Проверено на разных платформах.

Создание геометрии

Объекты GEOSGeometry можно создать несколькими способами. Первый — просто создать экземпляр объекта, передав пространственные данные. Ниже приведены примеры создания одной и той же геометрии из WKT, HEX, WKB и GeoJSON:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> pnt = GEOSGeometry("POINT(5 23)")  # WKT
>>> pnt = GEOSGeometry("010100000000000000000014400000000000003740")  # HEX
>>> pnt = GEOSGeometry(
...     memoryview(
...         b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x007@"
...     )
... )  # WKB
>>> pnt = GEOSGeometry(
...     '{ "type": "Point", "coordinates": [ 5.000000, 23.000000 ] }'
... )  # GeoJSON

Другой вариант — использовать конструктор конкретного типа геометрии, которую нужно создать. Например, объект Point можно создать, передав координаты X и Y в его конструктор:

>>> from django.contrib.gis.geos import Point
>>> pnt = Point(5, 23)

Все эти конструкторы принимают именованный аргумент srid. Например:

>>> from django.contrib.gis.geos import GEOSGeometry, LineString, Point
>>> print(GEOSGeometry("POINT (0 0)", srid=4326))
SRID=4326;POINT (0 0)
>>> print(LineString((0, 0), (1, 1), srid=4326))
SRID=4326;LINESTRING (0 0, 1 1)
>>> print(Point(0, 0, srid=32140))
SRID=32140;POINT (0 0)

Наконец, есть фабричный метод fromfile(), который возвращает объект GEOSGeometry из файла:

>>> from django.contrib.gis.geos import fromfile
>>> pnt = fromfile("/path/to/pnt.wkt")
>>> pnt = fromfile(open("/path/to/pnt.wkt"))

Геометрии соответствуют идиомам 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 – входное значение геометрии (строка или memoryview)
• 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:

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

classmethod GEOSGeometry.from_gml(gml_string)

Создаёт GEOSGeometry из заданной строки GML.

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 [исходный код]

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

Polygon

class Polygon(*args, **kwargs) [исходный код]

Объекты Polygon можно создать, передав параметры, представляющие кольца многоугольника. Параметры должны быть экземплярами LinearRing либо последовательностями, из которых можно создать LinearRing:

>>> ext_coords = ((0, 0), (0, 1), (1, 1), (1, 0), (0, 0))
>>> int_coords = ((0.4, 0.4), (0.4, 0.6), (0.6, 0.6), (0.6, 0.4), (0.4, 0.4))
>>> poly = Polygon(ext_coords, int_coords)
>>> poly = Polygon(LinearRing(ext_coords), LinearRing(int_coords))

classmethod from_bbox(bbox) [исходный код]

Возвращает объект многоугольника, построенный по заданной ограничивающей рамке — кортежу из 4 элементов, содержащему (xmin, ymin, xmax, ymax).

num_interior_rings [исходный код]

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

>>> if poly_1.area > poly_2.area:
...     pass
...

MultiPoint

class MultiPoint(*args, **kwargs) [исходный код]

Объекты MultiPoint можно создать, передав в качестве аргументов объекты Point либо одну последовательность объектов Point:

>>> mp = MultiPoint(Point(0, 0), Point(1, 1))
>>> mp = MultiPoint((Point(0, 0), Point(1, 1)))

MultiLineString

class MultiLineString(*args, **kwargs) [исходный код]

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

>>> ls1 = LineString((0, 0), (1, 1))
>>> ls2 = LineString((2, 2), (3, 3))
>>> mls = MultiLineString(ls1, ls2)
>>> mls = MultiLineString([ls1, ls2])

merged

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

closed

Возвращает True тогда и только тогда, когда все элементы замкнуты.

MultiPolygon

class MultiPolygon(*args, **kwargs) [исходный код]

Объекты MultiPolygon можно создать, передав в качестве аргументов объекты Polygon либо одну последовательность объектов Polygon:

>>> p1 = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> p2 = Polygon(((1, 1), (1, 2), (2, 2), (1, 1)))
>>> mp = MultiPolygon(p1, p2)
>>> mp = MultiPolygon([p1, p2])

GeometryCollection

class GeometryCollection(*args, **kwargs) [исходный код]

Объекты GeometryCollection можно создать, передав в качестве аргументов другие объекты GEOSGeometry либо одну последовательность объектов GEOSGeometry:

>>> poly = Polygon(((0, 0), (0, 1), (1, 1), (0, 0)))
>>> gc = GeometryCollection(Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly)
>>> gc = GeometryCollection((Point(0, 0), MultiPoint(Point(0, 0), Point(1, 1)), poly))

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)

Объекты чтения

Классы чтения и ввода-вывода возвращают экземпляр GEOSGeometry на основе данных WKB и/или WKT, переданных их методу read(geom).

class WKBReader [исходный код]

Пример:

>>> from django.contrib.gis.geos import WKBReader
>>> wkb_r = WKBReader()
>>> wkb_r.read("0101000000000000000000F03F000000000000F03F")
<Point object at 0x103a88910>

class WKTReader [исходный код]

Пример:

>>> from django.contrib.gis.geos import WKTReader
>>> wkt_r = WKTReader()
>>> wkt_r.read("POINT(1 1)")
<Point object at 0x103a88b50>

Объекты записи

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

class WKBWriter(dim=2) [исходный код]

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

write(geom) [исходный код]

Возвращает WKB заданной геометрии в виде объекта Python buffer. Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write(pnt)
<read-only buffer for 0x103a898f0, size -1, offset 0 at 0x103a89930>

write_hex(geom) [исходный код]

Возвращает WKB геометрии в шестнадцатеричном формате. Пример:

>>> from django.contrib.gis.geos import Point, WKBWriter
>>> pnt = Point(1, 1)
>>> wkb_w = WKBWriter()
>>> wkb_w.write_hex(pnt)
'0101000000000000000000F03F000000000000F03F'

byteorder

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

Значение Byteorder	Описание
0	От старшего байта к младшему (например, совместимо с системами 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 [исходный код]

Это свойство можно задать, чтобы изменить размерность выходного представления геометрии. Другими словами, если геометрия трёхмерная, задайте значение 3, чтобы координата Z включалась в WKB.

Значение Outdim	Описание
2	По умолчанию выводится двумерный WKB.
3	Выводится трёхмерный 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).