API GEOS

Что такое GEOS?

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

Функциональные возможности

GeoDjango реализует высокоуровневый Python-обёртку для библиотеки GEOS, её функциональные возможности включают:

• Интерфейс с лицензией BSD для геометрических функций GEOS, реализованный исключительно на 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"))

Геометрии — это 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) [source]

Параметры:

• geo_input – Значение входных данных геометрии (строка или memoryview)
• srid (int) – идентификатор пространственной системы координат

Это базовый класс для всех объектов геометрии GEOS. Он инициализируется заданным geo_input аргументом, а затем предполагает соответствующий подкласс геометрии (например, GEOSGeometry('POINT(1 1)') создаст объект Point).

Параметр srid, если задан, устанавливается в качестве SRID созданной геометрии, если у geo_input нет SRID. Если разные SRID предоставлены через geo_input и srid параметры, генерируется исключение ValueError:

>>> from django.contrib.gis.geos import GEOSGeometry
>>> GEOSGeometry("POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=4326;POINT EMPTY", srid=4326).ewkt
'SRID=4326;POINT EMPTY'
>>> GEOSGeometry("SRID=1;POINT EMPTY", srid=4326)
Traceback (most recent call last):
...
ValueError: Input geometry already has SRID: 1.

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

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

classmethod GEOSGeometry.from_gml(gml_string)

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

Point

class Point(x=None, y=None, z=None, srid=None) [source]

Объекты Point создаются с использованием аргументов, представляющих координаты составляющих точки, или с использованием одной последовательности координат. Например, следующие варианты эквивалентны:

>>> pnt = Point(5, 23)
>>> pnt = Point([5, 23])

Пустые объекты Point могут быть созданы, не передавая аргументов или пустой последовательностью. Следующие варианты эквивалентны:

>>> pnt = Point()
>>> pnt = Point([])

LineString

class LineString(*args, **kwargs) [source]

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

Возвращает, является ли эта линия замкнутой.

LinearRing

class LinearRing(*args, **kwargs) [source]

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

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

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

is_counterclockwise [source]

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

Polygon

class Polygon(*args, **kwargs) [source]

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

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

num_interior_rings [source]

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

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

MultiPoint

class MultiPoint(*args, **kwargs) [source]

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

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

MultiLineString

class MultiLineString(*args, **kwargs) [source]

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

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

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 [source]

Пример:

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

class WKTReader [source]

Пример:

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

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

write(geom) [source]

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

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

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

Установите это свойство со значением булевого типа, чтобы указать, следует ли включать 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) [source]

Этот класс позволяет выводить представление WKT геометрии. Подробнее о параметрах конструктора см. атрибуты WKBWriter.outdim, trim и precision.

write(geom) [source]

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

См. WKBWriter.outdim.

trim [source]

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

>>> 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 [source]

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