GDAL API

Примеры данных

Инструменты GDAL/OGR, описанные здесь, предназначены для помощи в чтении ваших пространственных данных. Для их эффективного использования необходимо иметь данные для работы. Если вы только начинаете и у вас ещё нет собственных данных для использования, тесты GeoDjango содержат ряд наборов данных, которые вы можете использовать для тестирования. Вы можете загрузить их здесь:

$ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
$ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif

DataSource

DataSource является оболочкой для объекта источника данных OGR, поддерживающего чтение данных из различных поддерживаемых OGR геопространственных форматов файлов и источников данных с помощью согласованного интерфейса. Каждый источник данных представлен объектом DataSource, который содержит один или несколько слоев данных. Каждый слой, представленный объектом Layer, содержит некоторое количество географических объектов (Feature), информацию о типе объектов, содержащихся в этом слое (например, точки, многоугольники и т. д.), а также имена и типы любых дополнительных полей (Field) данных, которые могут быть связаны с каждым объектом в этом слое.

class DataSource(ds_input, encoding='utf-8') [source]

Конструктор для DataSource требует только одного параметра: путь к файлу, который нужно прочитать. Однако OGR также поддерживает различные более сложные источники данных, включая базы данных, к которым можно получить доступ, передав специальную строку имени вместо пути. Для получения дополнительной информации см. документацию форматы векторных данных OGR. Свойство name экземпляра DataSource возвращает имя OGR базового источника данных, который он использует.

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

После создания DataSource, вы можете узнать, сколько слоев данных он содержит, обратившись к свойству layer_count или (эквивалентно) с помощью функции len(). Информацию о доступе к самим слоям данных см. в следующем разделе:

>>> from django.contrib.gis.gdal import DataSource
>>> ds = DataSource("/path/to/your/cities.shp")
>>> ds.name
'/path/to/your/cities.shp'
>>> ds.layer_count  # This file only contains one layer
1

layer_count [source]

Возвращает количество слоев в источнике данных.

name [source]

Возвращает имя источника данных.

Layer

class Layer

Layer — это оболочка слоя данных в объекте DataSource. Вы никогда не создаете объект Layer напрямую. Вместо этого вы получаете их из объекта DataSource, который по сути является стандартным контейнером Python объектов Layer. Например, вы можете получить доступ к определенному слою по его индексу (например, ds[0] для доступа к первому слою) или перебрать все слои в контейнере в цикле for. Сам объект Layer выступает в качестве контейнера для геометрических объектов.

Как правило, все объекты в данном слое имеют одинаковый тип геометрии. Свойство geom_type слоя является объектом OGRGeomType, который определяет тип объекта. Мы можем использовать его, чтобы вывести некоторую базовую информацию о каждом слое в DataSource:

>>> for layer in ds:
...     print('Layer "%s": %i %ss' % (layer.name, len(layer), layer.geom_type.name))
...
Layer "cities": 3 Points

Пример вывода из источника данных городов, загруженного выше, который, очевидно, содержит один слой, называемый "cities", который содержит три объекта типа точка. Для простоты примеры ниже предполагают, что вы сохранили этот слой в переменной layer:

>>> layer = ds[0]

name

Возвращает имя этого слоя в источнике данных.

>>> layer.name
'cities'

num_feat

Возвращает количество объектов в слое. То же, что и len(layer):

>>> layer.num_feat
3

geom_type

Возвращает тип геометрии слоя, как объект OGRGeomType:

>>> layer.geom_type.name
'Point'

num_fields

Возвращает количество полей в слое, т. е. количество полей данных, связанных с каждым объектом в слое:

>>> layer.num_fields
4

fields

Возвращает список имен каждого поля в этом слое:

>>> layer.fields
['Name', 'Population', 'Density', 'Created']

Возвращает список типов данных каждого поля в этом слое. Это подклассы Field, обсуждаемые ниже:

>>> [ft.__name__ for ft in layer.field_types]
['OFTString', 'OFTReal', 'OFTReal', 'OFTDate']

field_widths

Возвращает список максимальных длин полей для каждого поля в этом слое:

>>> layer.field_widths
[80, 11, 24, 10]

field_precisions

Возвращает список числовых точностей для каждого поля в этом слое. Это бессмысленно (и установлено в ноль) для полей, не являющихся числовыми:

>>> layer.field_precisions
[0, 0, 15, 0]

extent

Возвращает пространственный охват этого слоя в виде объекта Envelope:

>>> layer.extent.tuple
(-104.609252, 29.763374, -95.23506, 38.971823)

srs

Свойство, которое возвращает SpatialReference, связанное с этим слоем:

>>> print(layer.srs)
GEOGCS["GCS_WGS_1984",
    DATUM["WGS_1984",
        SPHEROID["WGS_1984",6378137,298.257223563]],
    PRIMEM["Greenwich",0],
    UNIT["Degree",0.017453292519943295]]

Если у слоя нет информации о пространственной системе координат, возвращается None.

spatial_filter

Свойство, которое можно использовать для получения или установки пространственного фильтра для этого слоя. Пространственный фильтр может быть установлен только с помощью экземпляра OGRGeometry, 4-кортежа охвата или None. При установке значения отличного от None, при итерации по слою будут возвращены только объекты, пересекающие фильтр:

>>> print(layer.spatial_filter)
None
>>> print(len(layer))
3
>>> [feat.get("Name") for feat in layer]
['Pueblo', 'Lawrence', 'Houston']
>>> ks_extent = (-102.051, 36.99, -94.59, 40.00)  # Extent for state of Kansas
>>> layer.spatial_filter = ks_extent
>>> len(layer)
1
>>> [feat.get("Name") for feat in layer]
['Lawrence']
>>> layer.spatial_filter = None
>>> len(layer)
3

get_fields()

Метод, который возвращает список значений данного поля для каждого объекта в слое:

>>> layer.get_fields("Name")
['Pueblo', 'Lawrence', 'Houston']

get_geoms(geos=False)

Метод, который возвращает список, содержащий геометрию каждого объекта в слое. Если необязательный аргумент geos установлен в True, то геометрии преобразуются в объекты GEOSGeometry. В противном случае они возвращаются как объекты OGRGeometry:

>>> [pt.tuple for pt in layer.get_geoms()]
[(-104.609252, 38.255001), (-95.23506, 38.971823), (-95.363151, 29.763374)]

test_capability(capability)

Возвращает булево значение, указывающее, поддерживает ли этот слой заданную возможность (строку). Примеры допустимых строк возможностей включают: 'RandomRead', 'SequentialWrite', 'RandomWrite', 'FastSpatialFilter', 'FastFeatureCount', 'FastGetExtent', 'CreateField', 'Transactions', 'DeleteFeature' и 'FastSetNextByIndex'.

Объекты данных

Объект Feature

Обёртка над объектом OGR feature. Вы никогда не создаёте объект Feature напрямую. Вместо этого, вы получаете их из объекта Layer. Каждый объект Feature состоит из геометрии и набора полей, содержащих дополнительные свойства. Геометрию поля можно получить через свойство geom, которое возвращает объект OGRGeometry. Объект Feature ведет себя как стандартный контейнер Python для своих полей, которые он возвращает как объекты Field: вы можете получить доступ к полю по его индексу или имени, или вы можете пройтись по полям объекта Feature, например, в цикле.

Свойство geom

Возвращает геометрию этого объекта Feature, как объект OGRGeometry:

feature_geom = feature.geom

Метод get

Метод, который возвращает значение заданного поля (указанного по имени) для этого объекта Feature, не объект-обёртку:

field_value = feature.get('field_name')

Свойство geom_type

Возвращает тип геометрии этого объекта Feature, как объект OGRGeomType. Он будет одинаковым для всех объектов Feature в данном слое и эквивалентен свойству geom_type объекта Layer, из которого получен объект Feature.

Свойство num_fields

Возвращает количество полей данных, связанных с объектом Feature. Оно будет одинаковым для всех объектов Feature в данном слое и эквивалентно свойству num_fields объекта Layer, из которого получен объект Feature.

Свойство fields

Возвращает список имён полей данных, связанных с объектом Feature. Оно будет одинаковым для всех объектов Feature в данном слое и эквивалентно свойству fields объекта Layer, из которого получен объект Feature.

Свойство fid

Возвращает идентификатор объекта Feature в пределах слоя:

feature_id = feature.fid

Свойство layer_name

Возвращает имя Layer, из которого получен объект Feature. Оно будет одинаковым для всех объектов Feature в данном слое:

layer_name = feature.layer_name

Метод index

Метод, который возвращает индекс заданного имени поля. Он будет одинаковым для всех объектов Feature в данном слое:

field_index = feature.index('field_name')

Поле

Класс Field

Свойство name

Возвращает имя этого поля:

field_name = field.name

Свойство type

Возвращает тип OGR этого поля, как целое число. Словарь FIELD_CLASSES отображает эти значения на подклассы Field:

field_type = field.type

Свойство type_name

Возвращает строку с именем типа данных этого поля:

field_type_name = field.type_name

Свойство value

Возвращает значение этого поля. Сам класс Field возвращает значение в виде строки, но каждый подкласс возвращает значение в наиболее подходящем формате:

field_value = field.value

Свойство width

Возвращает ширину этого поля:

field_width = field.width

Свойство precision

Возвращает числовую точность этого поля. Это бессмысленно (и установлено в ноль) для полей, не являющихся числовыми:

field_precision = field.precision

Метод as_double

Возвращает значение поля как double (float):

field_double = field.as_double()

Метод as_int

Возвращает значение поля как целое число:

field_int = field.as_int()

Метод as_string

Возвращает значение поля как строку:

field_string = field.as_string()

Метод as_datetime

Возвращает значение поля как кортеж компонентов даты и времени:

field_datetime = field.as_datetime()

Драйвер

Класс Driver[source]

Класс Driver используется для внутреннего обертывания OGR DataSource драйвера.

Свойство driver_count[source]

Возвращает количество зарегистрированных OGR векторных драйверов.

Объекты OGRGeometry

Объекты OGRGeometry обладают схожей функциональностью с объектами GEOSGeometry и являются тонкими оболочками над внутренним представлением геометрии OGR. Таким образом, они обеспечивают более эффективный доступ к данным при использовании DataSource. В отличие от своего аналога GEOS, OGRGeometry поддерживает системы пространственных ссылок и преобразование координат:

Класс OGRGeometry[source]

Этот объект является оболочкой для класса OGR Geometry. Эти объекты создаются непосредственно из переданного параметра geom_input, который может быть строкой, содержащей WKT, HEX, GeoJSON, buffer, содержащим данные WKB, или объектом OGRGeomType. Эти объекты также возвращаются атрибутом Feature.geom при чтении векторных данных из Layer (который, в свою очередь, является частью DataSource).

classmethod from_gml(gml_string) [source]

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

classmethod from_bbox(bbox) [source]

Создаёт Polygon из заданной прямоугольной области (четырёхэлементного кортежа).

__len__()

Возвращает количество точек в LineString, количество колец в Polygon или количество геометрий в GeometryCollection. Не применимо к другим типам геометрий.

__iter__()

Итерируется по точкам в LineString, по кольцам в Polygon или по геометриям в GeometryCollection. Не применимо к другим типам геометрий.

__getitem__()

Возвращает точку по указанному индексу для LineString, внутреннее кольцо по указанному индексу для Polygon или геометрию по указанному индексу в GeometryCollection. Не применимо к другим типам геометрий.

dimension [source]

Возвращает количество координатных измерений геометрии, например, 0 для точек, 1 для линий и т.д.:

>>> polygon.dimension
2

coord_dim [source]

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

Устаревшее с версии 5.1: Установщик coord_dim устарел. Используйте set_3d() вместо него.

is_3d [source]

Новое в Django 5.1.

Булево значение, указывающее, содержит ли эта геометрия Z-координаты.

set_3d(value) [source]

Новое в Django 5.1.

Метод, добавляющий или удаляющий Z-координатную размерность.

>>> p = OGRGeometry("POINT (1 2 3)")
>>> p.is_3d
True
>>> p.set_3d(False)
>>> p.wkt
"POINT (1 2)"

is_measured [source]

Новое в Django 5.1.

Булево значение, указывающее, содержит ли эта геометрия M-координаты.

set_measured(value) [source]

Новое в Django 5.1.

Метод добавления или удаления M-координатной размерности.

>>> p = OGRGeometry("POINT (1 2)")
>>> p.is_measured
False
>>> p.set_measured(True)
>>> p.wkt
"POINT M (1 2 0)"

geom_count [source]

Возвращает количество элементов в этой геометрии:

>>> polygon.geom_count
1

has_curve [source]

Новое в Django 5.2.

Булево значение, указывающее, является ли эта геометрия или содержит ли она кривую геометрию.

get_linear_geometry() [source]

Новое в Django 5.2.

Возвращает линейный вариант геометрии. Если преобразование невозможно, возвращается исходная геометрия.

get_curve_geometry() [source]

Новое в Django 5.2.

Возвращает кривую версию геометрии. Если преобразование невозможно, возвращается исходная геометрия.

point_count [source]

Возвращает количество точек, используемых для описания этой геометрии:

>>> polygon.point_count
4

num_points [source]

Псевдоним для point_count.

num_coords [source]

Псевдоним для point_count.

geom_type [source]

Возвращает тип этой геометрии как объект OGRGeomType.

geom_name [source]

Возвращает имя типа этой геометрии:

>>> polygon.geom_name
'POLYGON'

area [source]

Возвращает площадь этой геометрии или 0 для геометрий, не содержащих площади:

>>> polygon.area
25.0

envelope [source]

Возвращает охватывающую прямоугольник этой геометрии как объект Envelope.

extent [source]

Возвращает охватывающую прямоугольник этой геометрии как кортеж из 4 элементов вместо объекта Envelope:

>>> point.extent
(0.0, 0.0, 5.0, 5.0)

srs

Это свойство управляет системой пространственной привязки для этой геометрии или None, если ей не была назначена система пространственной привязки. Если назначена, доступ к этому свойству возвращает объект SpatialReference. Его можно установить с помощью другого объекта SpatialReference или любого входного значения, которое принимает SpatialReference. Пример:

>>> city.geom.srs.name
'GCS_WGS_1984'

srid

Возвращает или устанавливает идентификатор системы пространственной привязки, соответствующий SpatialReference этой геометрии. Возвращает None, если информация о системе пространственной привязки для этой геометрии отсутствует или SRID определить невозможно.

geos [source]

Возвращает объект GEOSGeometry, соответствующий этой геометрии.

gml [source]

Возвращает строковое представление этой геометрии в формате GML:

>>> OGRGeometry("POINT(1 2)").gml
'<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'

hex [source]

Возвращает строковое представление этой геометрии в формате HEX WKB:

>>> OGRGeometry("POINT(1 2)").hex
'0101000000000000000000F03F0000000000000040'

json [source]

Возвращает строковое представление этой геометрии в формате JSON:

>>> OGRGeometry("POINT(1 2)").json
'{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'

kml [source]

Возвращает строковое представление этой геометрии в формате KML.

wkb_size [source]

Возвращает размер буфера WKB, необходимого для хранения представления этой геометрии в формате WKB:

>>> OGRGeometry("POINT(1 2)").wkb_size
21

wkb [source]

Возвращает buffer, содержащий представление этой геометрии в формате WKB.

wkt [source]

Возвращает строковое представление этой геометрии в формате WKT.

ewkt [source]

Возвращает представление этой геометрии в формате EWKT.

clone() [source]

Возвращает новый клонированный объект OGRGeometry этой геометрии.

close_rings() [source]

Если в этой геометрии есть не замкнутые кольца, эта процедура закроет их, добавив начальную точку в конец:

>>> triangle = OGRGeometry("LINEARRING (0 0,0 1,1 0)")
>>> triangle.close_rings()
>>> triangle.wkt
'LINEARRING (0 0,0 1,1 0,0 0)'

transform(coord_trans, clone=False) [source]

Преобразует эту геометрию в другую систему пространственной привязки. Может принимать объект CoordTransform, объект SpatialReference или любое другое входное значение, принятое объектом SpatialReference (включая WKT и PROJ-строки систем пространственной привязки или целочисленный SRID).

По умолчанию ничего не возвращается, и геометрия преобразуется на месте. Однако, если ключевое слово clone установлено в значение True, вместо этого возвращается преобразованный клон этой геометрии.

intersects(other) [source]

Возвращает True, если эта геометрия пересекается с другой, в противном случае возвращает False.

equals(other) [source]

Возвращает True, если эта геометрия эквивалентна другой, в противном случае возвращает False.

disjoint(other) [source]

Возвращает True, если эта геометрия пространственно не пересекается с другой (т. е. не пересекается), в противном случае возвращает False.

touches(other) [source]

Возвращает True, если эта геометрия касается другой, в противном случае возвращает False.

crosses(other) [source]

Возвращает True, если эта геометрия пересекает другую, в противном случае возвращает False.

within(other) [source]

Возвращает True, если эта геометрия содержится в другой, в противном случае возвращает False.

contains(other) [source]

Возвращает True, если эта геометрия содержит другую, в противном случае возвращает False.

overlaps(other) [source]

Возвращает True, если эта геометрия перекрывается с другой, в противном случае возвращает False.

boundary() [source]

Граница этой геометрии, как новый объект OGRGeometry.

convex_hull [source]

Наименьший выпуклый многоугольник, содержащий эту геометрию, как новый объект OGRGeometry.

difference() [source]

Возвращает область, являющуюся разностью этой геометрии и другой, как новый объект OGRGeometry.

intersection() [source]

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

sym_difference() [source]

Возвращает область, являющуюся симметричной разностью этой геометрии и другой, как новый объект OGRGeometry объекта.

union() [source]

Возвращает область, являющуюся объединением этой геометрии и другой, как новый объект OGRGeometry.

centroid [source]

Возвращает Point, представляющий центр тяжести этой геометрии.

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

centroid был повышен от атрибута только для Polygon до доступности для всех типов геометрии.

tuple

Возвращает координаты геометрии точки в виде кортежа, координаты геометрии линии в виде кортежа кортежей и так далее:

>>> OGRGeometry("POINT (1 2)").tuple
(1.0, 2.0)
>>> OGRGeometry("LINESTRING (1 2,3 4)").tuple
((1.0, 2.0), (3.0, 4.0))

coords

Псевдоним для tuple.

class Point

x

Возвращает координату X этой точки:

>>> OGRGeometry("POINT (1 2)").x
1.0

y

Возвращает координату Y этой точки:

>>> OGRGeometry("POINT (1 2)").y
2.0

z

Возвращает координату Z этой точки или None, если у точки нет координаты Z:

>>> OGRGeometry("POINT (1 2 3)").z
3.0

m

Новое в Django 5.1.

Возвращает координату M этой точки или None, если у точки нет координаты M:

>>> OGRGeometry("POINT ZM (1 2 3 4)").m
4.0

class LineString

x

Возвращает список координат X в этой линии:

>>> OGRGeometry("LINESTRING (1 2,3 4)").x
[1.0, 3.0]

y

Возвращает список координат Y в этой линии:

>>> OGRGeometry("LINESTRING (1 2,3 4)").y
[2.0, 4.0]

z

Возвращает список координат Z в этой линии или None, если у линии нет координат Z:

>>> OGRGeometry("LINESTRING (1 2 3,4 5 6)").z
[3.0, 6.0]

m

Новое в Django 5.1.

Возвращает список координат M в этой линии или None, если у линии нет координат M:

>>> OGRGeometry("LINESTRING(0 1 2 10, 1 2 3 11, 2 3 4 12)").m
[10.0, 11.0, 12.0]

class Polygon

shell

Возвращает внешнее кольцо (shell) этого многоугольника в виде геометрии LinearRing.

exterior_ring

Псевдоним для shell.

class GeometryCollection

add(geom)

Добавляет геометрию в эту коллекцию геометрий. Не применимо к другим типам геометрии.

OGRGeomType

class OGRGeomType(type_input) [source]

Этот класс позволяет представлять тип OGR геометрии несколькими способами:

>>> from django.contrib.gis.gdal import OGRGeomType
>>> gt1 = OGRGeomType(3)  # Using an integer for the type
>>> gt2 = OGRGeomType("Polygon")  # Using a string
>>> gt3 = OGRGeomType("POLYGON")  # It's case-insensitive
>>> print(gt1 == 3, gt1 == "Polygon")  # Equivalence works w/non-OGRGeomType objects
True True

name [source]

Возвращает краткую строковую форму типа OGR геометрии:

>>> gt1.name
'Polygon'

num

Возвращает число, соответствующее типу OGR геометрии:

>>> gt1.num
3

django [source]

Возвращает тип поля Django (подкласс GeometryField) для хранения этого типа OGR или None, если нет соответствующего типа Django:

>>> gt1.django
'PolygonField'

Envelope

class Envelope(*args) [source]

Представляет структуру OGR Envelope, содержащую минимальные и максимальные координаты X и Y для прямоугольной области. Наименования переменных совместимы со структурой OGR Envelope C.

min_x [source]

Значение минимальной координаты X.

min_y [source]

Значение минимальной координаты Y.

max_x [source]

Значение максимальной координаты X.

max_y [source]

Значение максимальной координаты Y.

ur [source]

Координата верхнего правого угла, как кортеж.

ll [source]

Координата нижнего левого угла, как кортеж.

tuple [source]

Кортеж, представляющий область.

wkt [source]

Строка, представляющая данную область в формате WKT.

expand_to_include(*args) [source]

SpatialReference

class SpatialReference(srs_input) [source]

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

• OGC Well Known Text (WKT) (строка)
• Код EPSG (целое число или строка)
• Строка PROJ
• Сокращенная строка для общеизвестных стандартов ('WGS84', 'WGS72', 'NAD27', 'NAD83')

Пример:

>>> wgs84 = SpatialReference("WGS84")  # shorthand string
>>> wgs84 = SpatialReference(4326)  # EPSG code
>>> wgs84 = SpatialReference("EPSG:4326")  # EPSG string
>>> proj = "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs "
>>> wgs84 = SpatialReference(proj)  # PROJ string
>>> wgs84 = SpatialReference(
...     """GEOGCS["WGS 84",
... DATUM["WGS_1984",
...      SPHEROID["WGS 84",6378137,298.257223563,
...          AUTHORITY["EPSG","7030"]],
...      AUTHORITY["EPSG","6326"]],
... PRIMEM["Greenwich",0,
...      AUTHORITY["EPSG","8901"]],
... UNIT["degree",0.01745329251994328,
...      AUTHORITY["EPSG","9122"]],
... AUTHORITY["EPSG","4326"]]"""
... )  # OGC WKT

__getitem__(target) [source]

Возвращает значение узла атрибута заданной строки, None, если узел не существует. Также может принимать кортеж в качестве параметра, (target, child), где child — индекс атрибута в WKT. Например:

>>> wkt = 'GEOGCS["WGS 84", DATUM["WGS_1984, ... AUTHORITY["EPSG","4326"]]'
>>> srs = SpatialReference(wkt)  # could also use 'WGS84', or 4326
>>> print(srs["GEOGCS"])
WGS 84
>>> print(srs["DATUM"])
WGS_1984
>>> print(srs["AUTHORITY"])
EPSG
>>> print(srs["AUTHORITY", 1])  # The authority value
4326
>>> print(srs["TOWGS84", 4])  # the fourth value in this wkt
0
>>> print(srs["UNIT|AUTHORITY"])  # For the units authority, have to use the pipe symbol.
EPSG
>>> print(srs["UNIT|AUTHORITY", 1])  # The authority value for the units
9122

attr_value(target, index=0) [source]

Значение атрибута для заданного целевого узла (например, 'PROJCS'). Ключевое слово index указывает индекс дочернего узла для возврата.

auth_name(target) [source]

Возвращает имя организации для данного узла-цели (строка).

auth_code(target) [source]

Возвращает код организации для данного узла-цели (строка).

clone() [source]

Возвращает копию этого объекта пространственной привязки.

identify_epsg() [source]

Этот метод проверяет WKT этого SpatialReference и добавляет узлы авторитета EPSG, где применимо идентификатор EPSG.

from_esri() [source]

Преобразует эту пространственную привязку из формата ESRI в EPSG

to_esri() [source]

Преобразует эту пространственную привязку в формат ESRI.

validate() [source]

Проверяет, является ли заданная пространственная привязка валидной. В противном случае будет выброшено исключение.

import_epsg(epsg) [source]

Импортирует пространственную привязку из кода EPSG.

import_proj(proj) [source]

Импортирует пространственную привязку из строки PROJ.

import_user_input(user_input) [source]

import_wkt(wkt) [source]

Импортирует пространственную привязку из WKT.

import_xml(xml) [source]

Импортирует пространственную привязку из XML.

name [source]

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

srid [source]

Возвращает SRID верхнего уровня авторитета, или None, если не определено.

linear_name [source]

Возвращает имя линейных единиц.

linear_units [source]

Возвращает значение линейных единиц.

angular_name [source]

Возвращает имя угловых единиц.

angular_units [source]

Возвращает значение угловых единиц.

units [source]

Возвращает кортеж из двух элементов: значения единиц и их названия. Автоматически определяет, возвращать линейные или угловые единицы.

ellipsoid [source]

Возвращает кортеж параметров эллипсоида для этой пространственной привязки: (большая полуось, малая полуось, обратная сплюснутость).

semi_major [source]

Возвращает большую полуось эллипсоида для этой пространственной привязки.

semi_minor [source]

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

inverse_flattening [source]

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

geographic [source]

Возвращает True, если эта пространственная привязка географическая (корневой узел — GEOGCS).

local [source]

Возвращает True, если эта пространственная привязка локальная (корневой узел — LOCAL_CS).

projected [source]

Возвращает True, если эта система пространственных ссылок является проекционной системой координат (корневой узел является PROJCS).

wkt [source]

Возвращает представление WKT этой системы пространственных ссылок.

pretty_wkt [source]

Возвращает «красивое» представление WKT.

proj [source]

Возвращает представление PROJ для этой системы пространственных ссылок.

proj4 [source]

Псевдоним для SpatialReference.proj.

xml [source]

Возвращает XML-представление этой системы пространственных ссылок.

CoordTransform

class CoordTransform(source, target) [source]

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

>>> ct = CoordTransform(SpatialReference("WGS84"), SpatialReference("NAD83"))
>>> for feat in layer:
...     geom = feat.geom  # getting clone of feature geometry
...     geom.transform(ct)  # transforming
...

GDALRaster

GDALRaster является оболочкой для объекта источника растрового изображения GDAL, который поддерживает чтение данных из различных поддерживаемых GDAL геопространственных форматов файлов и источников данных с помощью согласованного интерфейса. Каждый источник данных представлен объектом GDALRaster, который содержит один или несколько слоев данных, называемых полосами. Каждая полоса, представленная объектом GDALBand, содержит геореференцированные данные изображения. Например, изображение RGB представлено тремя полосами: одной для красного, одной для зелёного и одной для синего цвета.

class GDALRaster(ds_input, write=False) [source]

Конструктор для GDALRaster принимает два параметра. Первый параметр определяет источник растра, а второй параметр определяет, должен ли растр открываться в режиме записи. Для вновь созданных растров второй параметр игнорируется, и новый растр всегда создаётся в режиме записи.

Первый параметр может принимать три формы: строка или Path, представляющие путь к файлу (файловая система или виртуальная файловая система GDAL), словарь со значениями, определяющими новый растр, или байтовый объект, представляющий файл растра.

Если вход представляет собой путь к файлу, растр открывается из него. Если вход представляет собой сырые данные в словаре, требуются параметры width, height и srid. Если вход представляет собой байтовый объект, он будет открыт с помощью виртуальной файловой системы GDAL.

Подробное описание создания растров с использованием входных данных в виде словаря см. в разделе Создание растров из данных. Подробное описание создания растров в виртуальной файловой системе см. в разделе Использование виртуальной файловой системы GDAL.

Следующий пример показывает, как растры можно создавать из различных источников входных данных (используя образцы данных из тестов GeoDjango; см. также раздел Данные образцов).

>>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster("/path/to/your/raster.tif", write=False)
>>> rst.name
'/path/to/your/raster.tif'
>>> rst.width, rst.height  # This file has 163 x 174 pixels
(163, 174)
>>> rst = GDALRaster(
...     {  # Creates an in-memory raster
...         "srid": 4326,
...         "width": 4,
...         "height": 4,
...         "datatype": 1,
...         "bands": [
...             {
...                 "data": (2, 3),
...                 "offset": (1, 1),
...                 "size": (2, 2),
...                 "shape": (2, 1),
...                 "nodata_value": 5,
...             }
...         ],
...     }
... )
>>> rst.srs.srid
4326
>>> rst.width, rst.height
(4, 4)
>>> rst.bands[0].data()
array([[5, 5, 5, 5],
       [5, 2, 3, 5],
       [5, 2, 3, 5],
       [5, 5, 5, 5]], dtype=uint8)
>>> rst_file = open("/path/to/your/raster.tif", "rb")
>>> rst_bytes = rst_file.read()
>>> rst = GDALRaster(rst_bytes)
>>> rst.is_vsi_based
True
>>> rst.name  # Stored in a random path in the vsimem filesystem.
'/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'

name [source]

Имя источника, которое эквивалентно пути к файлу входа или имени, предоставленному при создании.

>>> GDALRaster({"width": 10, "height": 10, "name": "myraster", "srid": 4326}).name
'myraster'

driver [source]

Имя драйвера GDAL, используемого для обработки входного файла. Для GDALRaster, созданных из файла, тип драйвера определяется автоматически. Создание растров с нуля по умолчанию является растром в памяти ('MEM'), но может быть изменено по мере необходимости. Например, используйте GTiff для файла GeoTiff. Список типов файлов также см. в списке Форматы растровых изображений GDAL.

Растр в памяти создаётся следующим образом:

>>> GDALRaster({"width": 10, "height": 10, "srid": 4326}).driver.name
'MEM'

Файл основанный растр GeoTiff создаётся следующим образом:

>>> import tempfile
>>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif")
>>> rst = GDALRaster(
...     {
...         "driver": "GTiff",
...         "name": rstfile.name,
...         "srid": 4326,
...         "width": 255,
...         "height": 255,
...         "nr_of_bands": 1,
...     }
... )
>>> rst.name
'/tmp/tmp7x9H4J.tif'           # The exact filename will be different on your computer
>>> rst.driver.name
'GTiff'

width [source]

Ширина источника в пикселях (ось X).

>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).width
10

height [source]

Высота источника в пикселях (ось Y).

>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).height
20

srs [source]

Система пространственной привязки растра, как экземпляр SpatialReference. SRS можно изменить, установив его в другой SpatialReference или предоставив любой входной параметр, принимаемый конструктором SpatialReference.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.srs.srid
4326
>>> rst.srs = 3086
>>> rst.srs.srid
3086

srid [source]

Идентификатор системы пространственной привязки (SRID) растра. Это свойство является сокращением для получения или установки SRID через атрибут srs.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.srid
4326
>>> rst.srid = 3086
>>> rst.srid
3086
>>> rst.srs.srid  # This is equivalent
3086

geotransform [source]

Матрица аффинного преобразования, используемая для геореференции источника, как кортеж из шести коэффициентов, которые отображают координаты пикселей/строк в геореференцированное пространство с помощью следующего соотношения:

Xgeo = GT(0) + Xpixel * GT(1) + Yline * GT(2)
Ygeo = GT(3) + Xpixel * GT(4) + Yline * GT(5)

Те же значения можно получить, обратившись к свойствам origin (индексы 0 и 3), scale (индексы 1 и 5) и skew (индексы 2 и 4).

По умолчанию [0.0, 1.0, 0.0, 0.0, 0.0, -1.0].

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.geotransform
[0.0, 1.0, 0.0, 0.0, 0.0, -1.0]

origin [source]

Координаты левого верхнего начала растра в системе пространственной привязки источника, как объект точки с x и y членами.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.origin
[0.0, 0.0]
>>> rst.origin.x = 1
>>> rst.origin
[1.0, 0.0]

scale [source]

Ширина и высота пикселей, используемые для геореференции растра, как объект точки с x и y членами. Подробнее см. geotransform.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.scale
[1.0, -1.0]
>>> rst.scale.x = 2
>>> rst.scale
[2.0, -1.0]

skew [source]

Коэффициенты наклона, используемые для геореференции растра, как объект точки с x и y членами. В случае изображений с направлением «север вверху» эти коэффициенты оба равны 0.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.skew
[0.0, 0.0]
>>> rst.skew.x = 3
>>> rst.skew
[3.0, 0.0]

extent [source]

Область (границы) источника растра, как 4-кортеж (xmin, ymin, xmax, ymax) в системе пространственной привязки источника.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.extent
(0.0, -20.0, 10.0, 0.0)
>>> rst.origin.x = 100
>>> rst.extent
(100.0, -20.0, 110.0, 0.0)

bands [source]

Список всех полос источника, как экземпляры GDALBand.

>>> rst = GDALRaster(
...     {
...         "width": 1,
...         "height": 2,
...         "srid": 4326,
...         "bands": [{"data": [0, 1]}, {"data": [2, 3]}],
...     }
... )
>>> len(rst.bands)
2
>>> rst.bands[1].data()
array([[ 2.,  3.]], dtype=float32)

warp(ds_input, resampling='NearestNeighbour', max_error=0.0) [source]

Возвращает искаженную версию этого растра.

Параметры искажения можно указать через аргумент ds_input. Использование ds_input аналогично соответствующему аргументу конструктора класса. Это словарь с характеристиками целевого растра. Разрешенные значения ключей словаря: ширина, высота, SRID, начало, масштаб, наклон, тип данных, драйвер и имя (имя файла).

По умолчанию функция warp сохраняет большинство параметров равными значениям исходного растра, поэтому необходимо указать только те параметры, которые следует изменить. Обратите внимание, что это включает драйвер, поэтому для растров на основе файлов функция warp создаст новый растр на диске.

Единственный параметр, который отличается от исходного растра, — это имя. Значение по умолчанию для имени растра — это имя исходного растра, добавленное '_copy' + source_driver_name. Для растров на основе файлов рекомендуется указать путь к файлу целевого растра.

Алгоритм ресемплирования, используемый для искажения, можно указать с помощью аргумента resampling. По умолчанию используется NearestNeighbor, а другие разрешенные значения — Bilinear, Cubic, CubicSpline, Lanczos, Average и Mode.

Аргумент max_error можно использовать для указания максимальной ошибки, измеряемой в пикселях входных данных, допускаемой при аппроксимации преобразования. По умолчанию значение равно 0,0 для точных расчетов.

Для пользователей, знакомых с GDAL, эта функция имеет функциональность, аналогичную командной утилите gdalwarp.

Например, функция warp может использоваться для агрегирования растра в два раза большего исходного масштаба пикселей:

>>> rst = GDALRaster(
...     {
...         "width": 6,
...         "height": 6,
...         "srid": 3086,
...         "origin": [500000, 400000],
...         "scale": [100, -100],
...         "bands": [{"data": range(36), "nodata_value": 99}],
...     }
... )
>>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3})
>>> target.bands[0].data()
array([[  7.,   9.,  11.],
       [ 19.,  21.,  23.],
       [ 31.,  33.,  35.]], dtype=float32)

transform(srs, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0) [source]

Преобразует этот растр в другую систему пространственных координат (srs), которая может быть объектом SpatialReference, или любым другим входным значением, принятым SpatialReference (включая WKT и PROJ-строки систем пространственных координат или целое число SRID).

Он вычисляет границы и масштаб текущего растра в новой системе пространственных координат и искажает растр с помощью функции warp.

По умолчанию используется драйвер исходного растра, а имя растра — это исходное имя, добавленное '_copy' + source_driver_name. Другой драйвер или имя можно указать с помощью аргументов driver и name.

По умолчанию алгоритм ресемплирования — NearestNeighbour, но его можно изменить с помощью аргумента resampling. По умолчанию максимальная допускаемая ошибка ресемплирования равна 0,0 и может быть изменена с помощью аргумента max_error. Обратитесь к документации warp для получения подробной информации об этих аргументах.

>>> rst = GDALRaster(
...     {
...         "width": 6,
...         "height": 6,
...         "srid": 3086,
...         "origin": [500000, 400000],
...         "scale": [100, -100],
...         "bands": [{"data": range(36), "nodata_value": 99}],
...     }
... )
>>> target_srs = SpatialReference(4326)
>>> target = rst.transform(target_srs)
>>> target.origin
[-82.98492744885776, 27.601924753080144]

info [source]

Возвращает строку с кратким описанием растра. Это эквивалентно командной утилите gdalinfo.

metadata

Метаданные этого растра, представленные в виде вложенного словаря. Ключ первого уровня — это домен метаданных. Второй уровень содержит имена и значения элементов метаданных из каждого домена.

Для установки или обновления элемента метаданных передайте соответствующий элемент метаданных в метод, используя описанную выше вложенную структуру. Обновляются только ключи, присутствующие в указанном словаре; остальные метаданные остаются неизменными.

Чтобы удалить элемент метаданных, используйте None в качестве значения метаданных.

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.metadata
{}
>>> rst.metadata = {"DEFAULT": {"OWNER": "Django", "VERSION": "1.0"}}
>>> rst.metadata
{'DEFAULT': {'OWNER': 'Django', 'VERSION': '1.0'}}
>>> rst.metadata = {"DEFAULT": {"OWNER": None, "VERSION": "2.0"}}
>>> rst.metadata
{'DEFAULT': {'VERSION': '2.0'}}

vsi_buffer [source]

bytes представление этого растра. Возвращает None для растров, которые не хранятся в виртуальной файловой системе GDAL.

is_vsi_based [source]

Булево значение, указывающее, хранится ли этот растр в виртуальной файловой системе GDAL.

GDALBand

class GDALBand

Экземпляры класса не создаются явно, а получаются из объекта GDALRaster через его атрибут bands. Объекты GDALBand содержат фактические значения пикселей растра.

description

Имя или описание полосы, если таковое имеется.

width

Ширина полосы в пикселях (ось X).

height

Высота полосы в пикселях (ось Y).

pixel_count

Общее количество пикселей в этой полосе. Равно width * height.

statistics(refresh=False, approximate=False)

Вычисление статистики по значениям пикселей этой полосы. Возвращаемое значение — кортеж со следующей структурой: (minimum, maximum, mean, standard deviation).

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

Если аргумент refresh установлен в True, статистика будет вычислена напрямую из данных, и кэш будет обновлён результатом.

Если найден постоянный кэшированный результат, он возвращается. Для форматов растровых данных, использующих службы постоянных вспомогательных метаданных (PAM), статистика может быть кэширована во вспомогательном файле. В некоторых случаях эти метаданные могут быть не синхронизированы со значениями пикселей, или возвращаться значения из предыдущего вызова, не отражающие значение аргумента approximate. В таких случаях используйте аргумент refresh для получения обновлённых значений и сохранения их в кэше.

Для пустых полос (где все значения пикселей — «нет данных»), все статистические данные возвращаются как None.

Статистику также можно получить, обратившись напрямую к свойствам min, max, mean и std.

min

Минимальное значение пикселя полосы (исключая значение «нет данных»).

max

Максимальное значение пикселя полосы (исключая значение «нет данных»).

mean

Среднее значение всех значений пикселей полосы (исключая значение «нет данных»).

std

Стандартное отклонение всех значений пикселей полосы (исключая значение «нет данных»).

nodata_value

Значение «нет данных» для полосы — это обычно специальное маркерное значение, используемое для обозначения пикселей, которые не являются действительными данными. Такие пиксели, как правило, не должны отображаться и не должны участвовать в операциях анализа.

Для удаления существующего значения «нет данных» установите это свойство в None.

datatype(as_string=False)

Тип данных, содержащихся в полосе, как целое число от 0 (Неизвестно) до 14. Если as_string равно True, тип данных возвращается как строка. Обратитесь к таблице значений типа datatype для возможных значений.

color_interp(as_string=False)

Интерпретация цвета для полосы, как целое число от 0 до 16. Если as_string равно True, тип данных возвращается как строка со следующими возможными значениями: GCI_Undefined, GCI_GrayIndex, GCI_PaletteIndex, GCI_RedBand, GCI_GreenBand, GCI_BlueBand, GCI_AlphaBand, GCI_HueBand, GCI_SaturationBand, GCI_LightnessBand, GCI_CyanBand, GCI_MagentaBand, GCI_YellowBand, GCI_BlackBand, GCI_YCbCr_YBand, GCI_YCbCr_CbBand и GCI_YCbCr_CrBand. GCI_YCbCr_CrBand также представляет собой GCI_Max, так как оба соответствуют целому числу 16, но только GCI_YCbCr_CrBand возвращается как строка.

data(data=None, offset=None, size=None, shape=None)

Доступ к значениям пикселей GDALBand. Возвращает весь массив данных, если параметры не указаны. Можно запросить подмножество массива пикселей, указав смещение и размер блока в виде кортежей.

Если NumPy доступен, данные возвращаются как массив NumPy. Для повышения производительности рекомендуется использовать NumPy.

Данные записываются в GDALBand, если параметр data указан. Входные данные могут быть одного из следующих типов — упакованная строка, буфер, список, массив и массив NumPy. Количество элементов ввода обычно должно соответствовать общему количеству пикселей в полосе или количеству пикселей для конкретного блока значений пикселей, если параметры offset и size указаны.

Если количество элементов ввода отличается от целевого блока пикселей, необходимо указать параметр shape. Форма — это кортеж, который задаёт ширину и высоту входных данных в пикселях. Затем данные дублируются для обновления значений пикселей выбранного блока. Это полезно, например, для заполнения всей полосы одним значением.

Пример:

>>> rst = GDALRaster(
...     {"width": 4, "height": 4, "srid": 4326, "datatype": 1, "nr_of_bands": 1}
... )
>>> bnd = rst.bands[0]
>>> bnd.data(range(16))
>>> bnd.data()
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]], dtype=int8)
>>> bnd.data(offset=(1, 1), size=(2, 2))
array([[ 5,  6],
       [ 9, 10]], dtype=int8)
>>> bnd.data(data=[-1, -2, -3, -4], offset=(1, 1), size=(2, 2))
>>> bnd.data()
array([[ 0,  1,  2,  3],
       [ 4, -1, -2,  7],
       [ 8, -3, -4, 11],
       [12, 13, 14, 15]], dtype=int8)
>>> bnd.data(data="\x9d\xa8\xb3\xbe", offset=(1, 1), size=(2, 2))
>>> bnd.data()
array([[  0,   1,   2,   3],
       [  4, -99, -88,   7],
       [  8, -77, -66,  11],
       [ 12,  13,  14,  15]], dtype=int8)
>>> bnd.data([1], shape=(1, 1))
>>> bnd.data()
array([[1, 1, 1, 1],
       [1, 1, 1, 1],
       [1, 1, 1, 1],
       [1, 1, 1, 1]], dtype=uint8)
>>> bnd.data(range(4), shape=(1, 4))
array([[0, 0, 0, 0],
       [1, 1, 1, 1],
       [2, 2, 2, 2],
       [3, 3, 3, 3]], dtype=uint8)

metadata

Метаданные этой полосы. Функциональность идентична GDALRaster.metadata.

Создание растров из данных

В этом разделе описывается, как создавать растры с нуля, используя параметр ds_input.

Новый растр создается, когда в конструктор GDALRaster передается словарь dict. Словарь содержит определяющие параметры нового растра, такие как начало координат, размер или система пространственной привязки. Словарь также может содержать пиксельные данные и информацию о формате нового растра. В результате растр может быть файловым или основанным на памяти, в зависимости от указанного драйвера.

Нет стандартного способа описания растровых данных в словаре или формате JSON. Определение входного словаря в класс GDALRaster поэтому специфично для Django. Оно вдохновлено форматом geojson, но стандарт geojson в настоящее время ограничен векторными форматами.

Примеры использования различных ключей при создании растров можно найти в документации соответствующих атрибутов и методов классов GDALRaster и GDALBand.

Использование виртуальной файловой системы GDAL

GDAL может обращаться к файлам, хранящимся в файловой системе, но также поддерживает виртуальные файловые системы для абстрагирования доступа к другим типам файлов, таким как сжатые, зашифрованные или удалённые файлы.

# Read a raster as a file object from a remote source.
>>> from urllib.request import urlopen
>>> dat = urlopen("https://example.com/raster.tif").read()
# Instantiate a raster from the bytes object.
>>> rst = GDALRaster(dat)
# The name starts with /vsimem/, indicating that the raster lives in the
# virtual filesystem.
>>> rst.name
'/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'

>>> from django.http import HttpResponse
>>> rst = GDALRaster(
...     {
...         "name": "/vsimem/temporarymemfile",
...         "driver": "tif",
...         "width": 6,
...         "height": 6,
...         "srid": 3086,
...         "origin": [500000, 400000],
...         "scale": [100, -100],
...         "bands": [{"data": range(36), "nodata_value": 99}],
...     }
... )
>>> HttpResponse(rast.vsi_buffer, "image/tiff")

>>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster("/vsizip/path/to/your/file.zip/path/to/raster.tif")
>>> rst = GDALRaster("/vsigzip/path/to/your/file.gz")
>>> rst = GDALRaster("/vsitar/path/to/your/file.tar/path/to/raster.tif")

>>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster("/vsicurl/https://example.com/raster.tif")
>>> rst.name
'/vsicurl/https://example.com/raster.tif'

GDAL_LIBRARY_PATH

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