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

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

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, или целое число 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¶

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

>>> 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 для ограничивающего прямоугольника. Именование переменных совместимо со структурой OGR Envelope C.

min_x¶

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

min_y¶

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

max_x¶

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

max_y¶

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

ur¶

Верхняя правая координата, в виде кортежа.

ll¶

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

tuple¶

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

wkt¶

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

expand_to_include(*args)¶

SpatialReference¶

class SpatialReference(srs_input)¶

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

• OGC Хорошо известный текст (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)¶

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

Переводит данную пространственную ссылку из формата ESRI в формат EPSG

to_esri()¶

Морфирует эту SpatialReference в формат ESRI.

validate()¶

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

import_epsg(epsg)¶

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

import_proj(proj)¶

Импорт пространственной ссылки из строки PROJ.

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¶

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

ellipsoid¶

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

semi_major¶

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

semi_minor¶

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

inverse_flattening¶

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

geographic¶

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

local¶

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

projected¶

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

wkt¶

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

pretty_wkt¶

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

proj¶

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

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

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

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

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

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

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

Changed in Django 4.0:

Создание растров в любой виртуальной файловой системе GDAL было разрешено.

name¶

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

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

driver¶

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

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

>>> 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. SRS можно изменить, установив ее в другое значение 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¶

Экстент (граничные значения) растрового источника, как 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 (имя файла).

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

Единственный параметр, который задается иначе, чем для исходного растра, - это имя. По умолчанию имя растра - это имя исходного растра, дополненное символом '_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. GDALBands содержит фактические значения пикселей растра.

description¶

Название или описание группы, если таковое имеется.

width¶

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

height¶

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

pixel_count¶

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

statistics(refresh=False, approximate=False)¶

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

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

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

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

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

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

min¶

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

max¶

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

mean¶

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

std¶

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

nodata_value¶

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

Чтобы удалить существующее значение «нет данных», установите это свойство в None.

datatype(as_string=False)¶

Тип данных, содержащихся в диапазоне, в виде целочисленной константы от 0 (Unknown) до 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.

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.

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

Не существует стандарта для описания растровых данных в виде словаря или 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('http://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).