API GDAL

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

Описанные здесь инструменты 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') [источник]

Для создания 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 [источник]

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

name [источник]

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

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, загруженного выше. Очевидно, он содержит один слой с именем "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]]

Если с Layer не связана информация о пространственной привязке, возвращается 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

class Feature

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

geom

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

>>> city.geom.tuple
(-104.609252, 38.255001)

get

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

>>> city.get("Population")
102121

geom_type

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

num_fields

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

fields

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

fid

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

>>> city.fid
0

layer_name

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

>>> city.layer_name
'cities'

index

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

>>> city.index("Population")
1

Field

class Field

name

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

>>> city["Name"].name
'Name'

type

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

>>> city["Density"].type
2

type_name

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

>>> city["Name"].type_name
'String'

value

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

>>> city["Population"].value
102121

width

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

>>> city["Name"].width
80

precision

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

>>> city["Density"].precision
15

as_double()

Возвращает значение поля в виде числа двойной точности (float):

>>> city["Density"].as_double()
874.7

as_int()

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

>>> city["Population"].as_int()
102121

as_string()

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

>>> city["Name"].as_string()
'Pueblo'

as_datetime()

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

>>> city["Created"].as_datetime()
(c_long(1999), c_long(5), c_long(23), c_long(0), c_long(0), c_long(0), c_long(0))

Driver

class Driver(dr_input) [источник]

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

driver_count [источник]

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

OGRGeometry

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

>>> from django.contrib.gis.gdal import OGRGeometry
>>> polygon = OGRGeometry("POLYGON((0 0, 5 0, 5 5, 0 5))")

class OGRGeometry(geom_input, srs=None) [исходный код]

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

classmethod from_gml(gml_string) [исходный код]

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

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

Создаёт Polygon из заданной ограничивающей рамки (кортежа из 4 элементов).

__len__()

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

__iter__()

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

__getitem__()

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

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

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

>>> polygon.dimension
2

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

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

set_3d(value) [исходный код]

Метод, который добавляет или удаляет измерение координаты Z.

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

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

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

set_measured(value) [исходный код]

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

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

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

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

>>> polygon.geom_count
1

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

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

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

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

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

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

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

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

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

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

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

>>> polygon.point_count
4

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

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

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

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

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

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

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

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

>>> polygon.geom_name
'POLYGON'

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

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

>>> polygon.area
25.0

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

Возвращает ограничивающую рамку этой геометрии в виде объекта Envelope.

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

Возвращает ограничивающую рамку этой геометрии в виде кортежа из 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 [исходный код]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

intersects(other) [исходный код]

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

equals(other) [исходный код]

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

disjoint(other) [исходный код]

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

touches(other) [исходный код]

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

crosses(other) [исходный код]

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

within(other) [исходный код]

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

contains(other) [исходный код]

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

overlaps(other) [исходный код]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Возвращает координату 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

Возвращает список координат 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

Возвращает оболочку или внешнее кольцо этого полигона в виде геометрии 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]

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

max_x [source]

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

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]

Преобразует эту SpatialReference из формата ESRI в EPSG

to_esri() [source]

Преобразует эту SpatialReference в формат 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]

Возвращает имя этой Spatial Reference.

srid [source]

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

linear_name [source]

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

linear_units [source]

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

angular_name [source]

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

angular_units [source]

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

units [source]

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

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

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

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

Если входные данные — путь к файлу, растр открывается по этому пути. Если входные данные представлены словарём с необработанными данными, обязательны параметры width, height и srid. Если входные данные — объект bytes, растр будет открыт с использованием виртуальной файловой системы 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 [исходный код]

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

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

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

Имя драйвера 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 [исходный код]

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

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

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

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

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

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

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

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

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

Идентификатор системы пространственной привязки растра (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 [исходный код]

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

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

Координаты начала растра в верхнем левом углу в системе пространственной привязки источника. Представлены объектом-точкой с членами 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 [исходный код]

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

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

Границы растрового источника в виде кортежа из четырёх значений (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 [исходный код]

Список всех каналов источника в виде экземпляров 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) [исходный код]

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

Параметры преобразования можно задать с помощью аргумента ds_input. Использование ds_input аналогично использованию соответствующего аргумента конструктора класса. Это словарь с характеристиками целевого растра. Допустимые ключи словаря: width, height, SRID, origin, scale, skew, datatype, driver и name (имя файла).

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

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

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

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

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

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

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

Преобразует этот растр в другую систему пространственной привязки (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 [исходный код]

Возвращает строку с кратким описанием растра. Эквивалент утилиты командной строки 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 [исходный код]

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

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

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

GDALBand

class GDALBand

Экземпляры 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 (Unknown) до 14. Если as_string равен True, тип данных возвращается в виде строки. Возможные значения см. в столбце «Тип пикселя GDAL» таблицы значений типов данных.

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