GDAL API — Django 文档
GDAL API
GDAL代表地理空间数据抽象库，是名副其实的GIS数据功能“瑞士军刀”。 GDAL 的一个子集是 OGR 简单特征库，它专门用于读取和写入各种标准格式的矢量地理数据。
GeoDjango 为 OGR 的一些功能提供了一个高级 Python 接口，包括矢量空间数据的读取和坐标转换以及对 GDAL 与栅格（图像）数据相关的功能的最小支持。
笔记
虽然该模块被命名为gdal，但GeoDjango目前仅支持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 矢量格式 文档。DataSource实例的 name 属性给出了它正在使用的底层数据源的 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 对象中检索它们，该对象本质上是Layer对象的标准 Python 容器。 例如，您可以通过索引访问特定图层（例如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'、[ X112X]、'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
返回此功能的给定字段（由名称指定）的值的方法，not 一个
Field包装器对象：>>> city.get('Population') 102121- geom_type
返回此特征的几何类型，作为 OGRGeomType 对象。 对于给定图层中的所有要素，这将相同，并且等效于该要素来自的 Layer 对象的 Layer.geom_type 属性。
- num_fields
返回与特征关联的数据字段数。 对于给定图层中的所有要素，这将相同，并且等效于该要素来自的 Layer 对象的 Layer.num_fields 属性。
- fields
返回与要素关联的数据字段的名称列表。 对于给定图层中的所有要素，这将相同，并且等效于该要素来自的 Layer 对象的 Layer.fields 属性。
- fid
返回图层内的特征标识符：
>>> city.fid 0- layer_name
返回特征来自的 层 的名称。 对于给定层中的所有特征，这将是相同的：
>>> 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()
以双精度（浮点数）形式返回该字段的值：
>>> 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 对象与 GEEOSGeometry 对象共享相似的功能，并且是 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 的字符串、包含 WKB 数据的buffer或 OGRGeomType 对象。 当从 Layer（又是 DataSource 的一部分）读取矢量数据时，这些对象也从 Feature.geom 属性返回。- classmethod from_gml(gml_string)
从给定的 GML 字符串构造一个 OGRGeometry。
- classmethod from_bbox(bbox)
从给定的边界框（一个 4 元组）构造一个 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
将此几何的包络作为 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 对应的空间参考标识符。 如果没有与此几何相关联的空间参考信息，或者无法确定 SRID，则返回
None。- 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
返回包含此几何图形的 WKB 表示的
buffer。- 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)
如果此几何体在空间上与（即 不相交）另一个，否则返回
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()
返回由这个几何体和另一个几何体的联合组成的区域，作为一个新的 OGRGGeometry 对象。
- 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 坐标，如果该点没有 Z 坐标，则返回
None：>>> 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 坐标列表，如果该行没有 Z 坐标，则返回
None：>>> 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
返回用于存储此 OGR 类型的 Django 字段类型（GeometryField 的子类），如果没有合适的 Django 类型，则返回
None：>>> gt1.django 'PolygonField'
Envelope
- class Envelope(*args)
表示包含矩形边界框的最小和最大 X、Y 坐标的 OGR Envelope 结构。 变量的命名与 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.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()
此方法检查此
SpatialReference的 WKT，并将在 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
如果此空间参考是地理参考（根节点为
GEOGCS），则返回True。- local
如果此空间参考是本地的（根节点是
LOCAL_CS），则返回True。- projected
如果此空间参考是投影坐标系（根节点为
PROJCS），则返回True。- wkt
返回此空间参考的 WKT 表示。
- pretty_wkt
返回 WKT 的“漂亮”表示。
- proj
返回此空间参考的 PROJ.4 表示。
- proj4
- 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 对象表示，该对象包含一个或多个名为 band 的数据层。 每个波段由 GDALBand 对象表示，包含地理参考图像数据。 例如，RGB 图像表示为三个波段：一个用于红色，一个用于绿色，一个用于蓝色。
笔记
对于栅格数据，栅格实例与其数据源之间没有区别。 与 Geometry 对象不同，GDALRaster 对象始终是数据源。 临时栅格可以使用相应的驱动程序在内存中实例化，但它们将与基于文件的栅格源属于同一类。
- class GDALRaster(ds_input, write=False)
GDALRaster的构造函数接受两个参数。 第一个参数定义栅格源，第二个参数定义是否应以写入模式打开栅格。 对于新创建的栅格，第二个参数将被忽略，并且新栅格始终以写入模式创建。第一个参数可以采用三种形式：表示文件路径的字符串、具有定义新光栅的值的字典或表示光栅文件的字节对象。
如果输入是文件路径，则从那里打开栅格。 如果输入是字典中的原始数据，则需要参数
width、height和srid。 如果输入是字节对象，它将使用 GDAL 虚拟文件系统打开。有关如何使用字典输入创建栅格的详细说明，请参阅 从数据创建栅格 。 有关如何在虚拟文件系统中创建栅格的详细说明，请参阅 使用 GDAL 的虚拟文件系统 。
以下示例显示了如何从不同的输入源创建栅格（使用来自 GeoDjango 测试的示例数据；另见 示例数据 部分）。
>>> from django.contrib.gis.gdal import GDALRaster >>> rst = GDALRaster('/path/to/your/raster.tif', write=False) >>> rst.name '/path/to/your/raster.tif' >>> rst.width, rst.height # This file has 163 x 174 pixels (163, 174) >>> rst = GDALRaster({ # Creates an in-memory raster ... 'srid': 4326, ... 'width': 4, ... 'height': 4, ... 'datatype': 1, ... 'bands': [{ ... 'data': (2, 3), ... 'offset': (1, 1), ... 'size': (2, 2), ... 'shape': (2, 1), ... 'nodata_value': 5, ... }] ... }) >>> rst.srs.srid 4326 >>> rst.width, rst.height (4, 4) >>> rst.bands[0].data() array([[5, 5, 5, 5], [5, 2, 3, 5], [5, 2, 3, 5], [5, 5, 5, 5]], dtype=uint8) >>> rst_file = open('/path/to/your/raster.tif', 'rb') >>> rst_bytes = rst_file.read() >>> rst = GDALRaster(rst_bytes) >>> rst.is_vsi_based True >>> rst.name # Stored in a random path in the vsimem filesystem. '/vsimem/da300bdb-129d-49a8-b336-e410a9428dad'- name
源的名称，相当于输入文件路径或实例化时提供的名称。
>>> GDALRaster({'width': 10, 'height': 10, 'name': 'myraster', 'srid': 4326}).name 'myraster'
- driver
用于处理输入文件的 GDAL 驱动程序的名称。 对于从文件创建的
GDALRaster，会自动检测驱动程序类型。 默认情况下，从头开始创建的栅格是内存中的栅格 ('MEM')，但可以根据需要进行更改。 例如，对GeoTiff文件使用GTiff。 有关文件类型列表，另请参阅 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 实例。 可以通过将 SRS 设置为其他 SpatialReference 或提供 SpatialReference 构造函数接受的任何输入来更改 SRS。
>>> rst = GDALRaster({'width': 10, 'height': 20, 'srid': 4326}) >>> rst.srs.srid 4326 >>> rst.srs = 3086 >>> rst.srs.srid 3086
- srid
栅格的空间参考系统标识符 (SRID)。 此属性是通过 srs 属性获取或设置 SRID 的快捷方式。
>>> 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的使用类似于类构造函数的相应参数。 它是具有目标栅格特征的字典。 允许的字典键值为宽度、高度、SRID、原点、比例、倾斜、数据类型、驱动程序和名称（文件名）。默认情况下，warp 函数使大多数参数与原始源栅格的值相同，因此只需要指定应该更改的参数。 请注意，这包括驱动程序，因此对于基于文件的栅格，warp 函数将在磁盘上创建一个新栅格。
与源栅格设置不同的唯一参数是名称。 栅格名称的默认值是源栅格名称后附加
'_copy' + source_driver_name。 对于基于文件的栅格，建议提供目标栅格的文件路径。可以使用
resampling参数指定用于变形的重采样算法。 默认为NearestNeighbor，其他允许值为Bilinear、Cubic、CubicSpline、Lanczos、Average, 和Mode。max_error参数可用于指定在近似变换中允许的输入像素中测量的最大误差。 精确计算的默认值为 0.0。对于熟悉
GDAL的用户，此功能具有与gdalwarp命令行实用程序类似的功能。例如，warp 函数可用于将栅格聚合为其原始像素比例的两倍：
>>> rst = GDALRaster({ ... "width": 6, "height": 6, "srid": 3086, ... "origin": [500000, 400000], ... "scale": [100, -100], ... "bands": [{"data": range(36), "nodata_value": 99}] ... }) >>> target = rst.warp({"scale": [200, -200], "width": 3, "height": 3}) >>> target.bands[0].data() array([[ 7., 9., 11.], [ 19., 21., 23.], [ 31., 33., 35.]], dtype=float32)
- transform(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]
- 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表示。 对于未存储在 GDAL 的虚拟文件系统中的栅格，返回None。
- is_vsi_based
一个布尔值，指示此栅格是否存储在 GDAL 的虚拟文件系统中。
GDALBand
- class GDALBand
GDALBand实例不是显式创建的，而是通过 bands 属性从 GDALRaster 对象中获取的。 GDALBands 包含光栅的实际像素值。- description
乐队的名称或描述（如果有）。
- width
带的宽度（以像素为单位）（X 轴）。
- height
带的高度（以像素为单位）（Y 轴）。
- pixel_count
此波段中的像素总数。 等于
width * height。
- statistics(refresh=False, approximate=False)
计算此波段的像素值的统计信息。 返回值是一个具有以下结构的元组：
(minimum, maximum, mean, standard deviation)。如果
approximate参数设置为True，则可以根据概览或图像块的子集计算统计数据。如果
refresh参数设置为True，则将直接从数据计算统计信息，并将结果更新缓存。如果找到持久缓存值，则返回该值。 对于使用持久辅助元数据 (PAM) 服务的栅格格式，统计信息可能会缓存在辅助文件中。 在某些情况下，此元数据可能与像素值不同步，或者导致上次调用的值返回，而这些值不反映
approximate参数的值。 在这种情况下，使用refresh参数来获取更新的值并将它们存储在缓存中。对于空波段（其中所有像素值都是“无数据”），所有统计数据都以
None形式返回。
- min
波段的最小像素值（不包括“无数据”值）。
- max
波段的最大像素值（不包括“无数据”值）。
- mean
波段所有像素值的平均值（不包括“无数据”值）。
- std
波段所有像素值的标准偏差（不包括“无数据”值）。
- nodata_value
波段的“无数据”值通常是一个特殊的标记值，用于标记无效数据的像素。 通常不应显示此类像素，也不应参与分析操作。
要删除现有的“无数据”值，请将此属性设置为
None（需要 GDAL ≥ 2.1）。
- 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、 X215X] 和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、 X215X]、GCI_MagentaBand、GCI_YellowBand、GCI_BlackBand、GCI_YCbCr_YBand、GCI_YCbCr_CbBand、GCI_YCbCr_CrBand也代表GCI_Max，因为两者都对应整数 16，但只有GCI_YCbCr_CrBand作为字符串返回。
- data(data=None, offset=None, size=None, shape=None)
GDALBand像素值的访问器。 如果没有提供参数，则返回完整的数据数组。 可以通过将偏移量和块大小指定为元组来请求像素阵列的子集。如果 NumPy 可用，则数据作为 NumPy 数组返回。 出于性能原因，强烈建议使用 NumPy。
如果提供
data参数，数据将写入GDALBand。 输入可以是以下类型之一 - 压缩字符串、缓冲区、列表、数组和 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 类的相应属性和方法的文档中找到。
ds_input 字典
在 ds_input 字典中只需要几个键即可创建栅格：width、height 和 srid。 所有其他参数都有默认值（见下表）。 可以在 ds_input 字典中传递的键列表与 GDALRaster 属性密切相关但不完全相同。 许多参数直接映射到这些属性； 其他的描述如下。
下表描述了 ds_input 字典中可以设置的所有键。
| 键 | 默认 | 如何使用 |
|---|---|---|
srid
|
必须的 | 映射到 srid 属性 |
width
|
必须的 | 映射到 width 属性 |
height
|
必须的 | 映射到 height 属性 |
driver
|
MEM
|
映射到 driver 属性 |
name
|
|
见下文 |
origin
|
0
|
映射到 origin 属性 |
scale
|
0
|
映射到 scale 属性 |
skew
|
0
|
映射到 width 属性 |
bands
|
[]
|
见下文 |
nr_of_bands
|
0
|
见下文 |
datatype
|
6
|
见下文 |
papsz_options
|
{}
|
见下文 |
- name
- 表示栅格名称的字符串。 创建基于文件的栅格时，此参数必须是新栅格的文件路径。 如果名称以
/vsimem/开头，则栅格将在 GDAL 的虚拟文件系统中创建。
- 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。
- papsz_options
带有栅格创建选项的字典。 输入字典的键值对在创建栅格时传递给驱动程序。
可用选项是特定于驱动程序的，并在每个驱动程序的文档中进行了描述。
字典中的值不区分大小写，并在创建时自动转换为正确的字符串格式。
以下示例使用了一些可用于 GTiff 驱动程序 的选项。 结果是带有内部切片方案的压缩有符号字节栅格。 内部磁贴的块大小为 23 x 23：
>>> GDALRaster({ ... 'driver': 'GTiff', ... 'name': '/path/to/new/file.tif', ... 'srid': 4326, ... 'width': 255, ... 'height': 255, ... 'nr_of_bands': 1, ... 'papsz_options': { ... 'compress': 'packbits', ... 'pixeltype': 'signedbyte', ... 'tiled': 'yes', ... 'blockxsize': 23, ... 'blockysize': 23, ... } ... })
band_input 字典
ds_input 字典中的 bands 键是 band_input 字典的列表。 每个 band_input 字典都可以包含像素值和要在新栅格波段上设置的“无数据”值。 数据数组可以具有新栅格的完整大小或更小。 对于小于完整光栅的阵列，size、shape 和 offset 键控制像素值。 相应的键被传递给 data() 方法。 它们的功能与使用该方法设置波段数据相同。 下表描述了可以使用的键。
| 键 | 默认 | 如何使用 |
|---|---|---|
nodata_value
|
None
|
映射到 nodata_value 属性 |
data
|
与 nodata_value 或 0 相同
|
传递给 data() 方法 |
size
|
(with, height) 光栅
|
传递给 data() 方法 |
shape
|
大小一样 | 传递给 data() 方法 |
offset
|
(0, 0)
|
传递给 data() 方法 |
使用 GDAL 的虚拟文件系统
GDAL 有一个基于内部内存的文件系统，它允许将内存块视为文件。 它可用于从二进制文件缓冲区读取和写入 GDALRaster 对象。
这在 Web 上下文中很有用，其中栅格可以作为缓冲区从远程存储获取或从视图返回而不写入磁盘。
GDALRaster 对象是在提供 bytes 对象作为输入时，或文件路径以 /vsimem/ 开头时在虚拟文件系统中创建的。
作为 bytes 提供的输入必须是文件的完整二进制表示。 例如：
# 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'要从头开始创建新的基于虚拟文件的栅格，请使用 ds_input 字典表示并提供以 /vsimem/ 开头的 name 参数（有关字典表示的详细信息，请参阅从数据创建栅格)。 对于基于虚拟文件的栅格，vsi_buffer 属性返回栅格的 bytes 表示。
以下是创建栅格并将其作为 HttpResponse 中的文件返回的方法：
>>> 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')配置
GDAL_LIBRARY_PATH
指定 GDAL 库位置的字符串。 通常，仅当 GDAL 库位于非标准位置（例如，/home/john/lib/libgdal.so）时才使用此设置。
例外
- exception GDALException
- 基本 GDAL 异常，指示与 GDAL 相关的错误。
- exception SRSException
- 构造或使用空间参考系统对象时发生错误时引发的异常。
