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 могут быть созданы несколькими способами. Первый - это просто инстанцировать объект на каком-либо пространственном входе - ниже приведены примеры создания одной и той же геометрии из 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'))

Геометрии пифонические¶

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

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

Для формата 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>

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

Все объекты 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)'

Сноски

GEOS_LIBRARY_PATH¶

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