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", который содержит три точки. Для простоты примеры ниже предполагают, что вы сохранили этот слой в переменной 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()

Возвращает значение поля как 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_bbox(bbox)

Создаёт Polygon из заданного прямоугольника (кортежа из 4 элементов).

__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

Возвращает охватывающий прямоугольник этой геометрии как кортеж из 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.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) или внешнюю линию этого многоугольника, как геометрию LinearRing.

exterior_ring

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

centroid

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

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

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

>>> gt1.name
'Polygon'

num

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

>>> gt1.num
3

django

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

>>> gt1.django
'PolygonField'

Envelope

class Envelope(*args) [source]

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

min_x

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

min_y

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

max_x

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

max_y

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

ur

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

ll

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

tuple

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

wkt

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

expand_to_include(*args) [source]

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

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({'srid': 4326, 'width': 1, 'height': 2, 'datatype': 1
...                   'bands': [{'data': [0, 1]}]}) # Creates in-memory raster
>>> rst.srs.srid
4326
>>> rst.width, rst.height
(1, 2)
>>> rst.bands[0].data()
array([[0, 1]], dtype=int8)

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

Теперь объекты GDALRaster можно создавать непосредственно из исходных данных. Добавлены методы установки следующих свойств: srs, geotransform, origin, scale, и skew.

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)

Новое в Django 1.9.

Возвращает деформированную версию этого растрового изображения.

Параметры деформации можно указать с помощью аргумента 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)

Новое в Django 1.9.

Возвращает преобразованную версию этого растрового изображения с указанным 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

Новое в Django 1.9.

Общее количество пикселей в этой полосе. Равно 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.9:

Это свойство теперь также может быть установлено.

Изменено в 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)

Новое в Django 1.9.

Доступ к значениям пикселей 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.

Настройки

GDAL_LIBRARY_PATH

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