GDAL API

GDAL означает Библиотеку геопространственного абстрагирования данных, являющуюся настоящим «ножом швейцарского армейского образца» для функций работы с данными ГИС. Подмножество GDAL — OGR, библиотека простых объектов, специализирующаяся на чтении и записи векторных географических данных в различных стандартных форматах.

GeoDjango предоставляет высокоуровневый Python-интерфейс для некоторых возможностей OGR, включая чтение и преобразование координат векторных пространственных данных и минимальную поддержку функций GDAL в отношении растровых (изображений) данных.

Обзор

Образцы данных

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

$ wget https://raw.githubusercontent.com/django/django/master/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
$ wget https://raw.githubusercontent.com/django/django/master/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 Vector Formats. Свойство 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]]

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

spatial_filter

Свойство, которое может использоваться для извлечения или задания пространственного фильтра для данного слоя. Пространственный фильтр можно задать только с экземпляром OGRGeometry, четырёхэлементным кортежем расширения или 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. Вы никогда не создаёте объект Feature напрямую. Вместо этого, вы получаете их из объекта Layer. Каждый объект Feature состоит из геометрии и набора полей, содержащих дополнительные свойства. Геометрия поля доступна через свойство geom , которое возвращает объект OGRGeometry. Объект Feature ведет себя как стандартный контейнер Python для своих полей, которые он возвращает как объекты Field: вы можете получить доступ к полю напрямую по его индексу или имени, или вы можете перебрать поля объекта Feature, например, в цикле for.

geom

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

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

get

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

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

geom_type

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

num_fields

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

fields

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

fid

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

>>> city.fid
0

layer_name

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

>>> city.layer_name
'cities'

index

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

>>> 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 векторных данных.

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)

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

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

classmethod from_bbox(bbox)

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

__len__()

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

__iter__()

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

__getitem__()

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

dimension

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

>> polygon.dimension
2

coord_dim

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

geom_count

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

>>> polygon.geom_count
1

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

Возвращает прямоугольную область этой геометрии как четвёрку чисел, вместо объекта 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.4 строки или целочисленный 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 объект.

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

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]

class Polygon

shell

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

exterior_ring

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

centroid

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

class GeometryCollection

add(geom)

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

OGRGeomType

class OGRGeomType(type_input)

Этот класс позволяет представлять тип 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

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

>>> gt1.name
'Polygon'

num

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

>>> gt1.num
3

django

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

>>> gt1.django
'PolygonField'

Envelope

class Envelope(*args)

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

min_x

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

min_y

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

max_x

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

max_y

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

ur

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

ll

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

tuple

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

wkt

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

expand_to_include(*args)

Объекты систем координат

SpatialReference

class SpatialReference(srs_input)

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

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

Пример:

>>> wgs84 = SpatialReference('WGS84') # shorthand string
>>> wgs84 = SpatialReference(4326) # EPSG code
>>> wgs84 = SpatialReference('EPSG:4326') # EPSG string
>>> proj4 = '+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs '
>>> wgs84 = SpatialReference(proj4) # PROJ.4 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)

Возвращает значение заданного узла атрибута строки, 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)

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

auth_name(target)

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

auth_code(target)

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

clone()

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

identify_epsg()

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

from_esri()

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

to_esri()

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

validate()

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

import_epsg(epsg)

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

import_proj(proj)

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

import_user_input(user_input)

import_wkt(wkt)

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

import_xml(xml)

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

name

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

srid

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

linear_name

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

linear_units

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

angular_name

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

angular_units

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

units

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

ellipsoid

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

semi_major

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

semi_minor

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

inverse_flattening

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

geographic

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

local

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

projected

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

wkt

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

pretty_wkt

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

proj

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

proj4

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

xml

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

CoordTransform

class CoordTransform(source, target)

Представляет преобразование системы координат. Инициализируется двумя 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 принимает два параметра. Первый параметр определяет источник растра, это может быть путь к файлу или пространственные данные со значениями, определяющими свойства нового растра (такие как размер и имя). Если вход представляет собой путь к файлу, второй параметр указывает, должен ли растр открываться с правами записи. Если вход представляет собой сырые данные, требуются параметры width, height, и srid. Следующий пример демонстрирует создание растров из разных источников данных (используя примерные данные из тестов 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)

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

Добавлена возможность передачи параметров size, shape, и offset при создании объектов GDALRaster. Параметры могут быть переданы через словарь ds_input. Это позволяет точно контролировать начальные значения пикселей. Функциональность аналогична методу GDALBand.data().

name

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

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

driver

Имя драйвера GDAL, используемого для обработки входного файла. Для растров, созданных из файла, тип драйвера определяется автоматически. Создание растров «с нуля» по умолчанию происходит в оперативной памяти ('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

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

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

Пределы (границы) источника растра, как кортеж из 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

Список всех полос источника, как экземпляры 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(srid, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0)

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

Эта функция преобразует текущий растр в новую систему пространственной привязки, которую можно указать с помощью 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 = rst.transform(4326)
>>> target.origin
[-82.98492744885776, 27.601924753080144]

GDALBand

class GDALBand

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

description

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

width

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

height

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

pixel_count

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

statistics(refresh=False, approximate=False)

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

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

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

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

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

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

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

min

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

max

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

mean

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

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

std

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

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

nodata_value

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

Чтобы удалить существующее значение «нет данных», установите это свойство в None (требуется GDAL ≥ 2.1).

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

Теперь значение «нет данных» можно удалить, установив атрибут nodata_value в None.

datatype(as_string=False)

Тип данных в полосе, как целочисленная константа от 0 (Неизвестно) до 11. Если as_string равно True, тип данных возвращается как строка со следующими возможными значениями: GDT_Unknown, GDT_Byte, GDT_UInt16, GDT_Int16, GDT_UInt32, GDT_Int32, GDT_Float32, GDT_Float64, GDT_CInt16, GDT_CInt32, GDT_CFloat32, и GDT_CFloat64.

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)

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

Добавлен параметр shape и возможность дублирования входных данных при установке данных GDALBand.

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

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

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

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

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

Словарь ds_input

Для создания растра в словаре ds_input требуются только несколько ключей: width, height, и srid. Все остальные параметры имеют значения по умолчанию (см. таблицу ниже). Список ключей, которые можно передать в словаре ds_input, тесно связан, но не идентичен свойствам GDALRaster. Многие параметры напрямую сопоставляются с этими свойствами; остальные описаны ниже.

В таблице ниже описаны все ключи, которые можно установить в словаре ds_input.

name

Строка, представляющая имя растра. При создании растра на основе файла этот параметр должен содержать путь к файлу для нового растра.

datatype

Целое число, представляющее тип данных для всех полос. По умолчанию 6 (Float32). Все полосы нового растра должны иметь один и тот же тип данных. Соответствие значений:

Значение	Тип пикселя GDAL	Описание
1	GDT_Byte	Восьмибитовое беззнаковое целое число
2	GDT_UInt16	Шестнадцатибитовое беззнаковое целое число
3	GDT_Int16	Шестнадцатибитовое знаковое целое число
4	GDT_UInt32	Тридцатидвухбитовое беззнаковое целое число
5	GDT_Int32	Тридцатидвухбитовое знаковое целое число
6	GDT_Float32	Тридцатидвухбитовое число с плавающей точкой
7	GDT_Float64	Шестидесятичетырёхбитовое число с плавающей точкой

nr_of_bands

Целое число, представляющее количество полос растра. Растр можно создать, не передавая данные полос при создании. Если количество полос не указано, оно автоматически вычисляется из длины входного параметра bands. Количество полос изменить после создания нельзя.

bands

Список словарей band_input с входными данными полос. Полученные индексы полос совпадают с индексами в предоставленном списке. Определение словаря входных данных полосы приведено ниже. Если данные полос не предоставлены, значения полос растра инициализируются массивом нулей, а значение «нет данных» устанавливается в None.

Словарь входных данных полосы

Ключ bands в словаре ds_input представляет собой список словарей band_input. Каждый словарь band_input может содержать значения пикселей и значение «нет данных», которое нужно установить для полос нового растра. Массив данных может иметь полный размер нового растра или быть меньше. Для массивов, меньших полного растра, ключи size, shape, и offset управляют значениями пикселей. Соответствующие ключи передаются методу data(). Их функциональность аналогична установке данных полосы с помощью этого метода. В следующей таблице описаны используемые ключи.

Настройки

GDAL_LIBRARY_PATH

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

Исключения

exception GDALException

Базовое исключение GDAL, указывающее на ошибку, связанную с GDAL.

exception SRSException

Исключение, возникающее при ошибке построения или использования объекта системы пространственной привязки.