示例数据¶

此处描述的 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) 的名称和类型。

类 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¶

图层 是 DataSource 对象中数据图层的一个包装器。您永远不会直接创建一个 图层 对象。相反，您可以从 DataSource 对象中检索它们，该对象本质上是 图层 对象的标准 Python 容器。例如，您可以通过其索引访问特定图层（例如 ds[0] 访问第一个图层），或者您可以在 for 循环中迭代容器中的所有图层。 图层 本身充当几何要素的容器。

通常，给定图层中的所有要素具有相同的几何类型。图层的 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 对象的 Layer.geom_type 属性。

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¶

名称¶

返回此字段的名称

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

类型¶

返回此字段的 OGR 类型，为整数。 FIELD_CLASSES 字典将这些值映射到 Field 的子类

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

类型名称¶

返回一个字符串，其中包含此字段的数据类型的名称

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

值¶

返回此字段的值。 Field 类本身将值作为字符串返回，但每个子类都以最合适的形式返回值

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

宽度¶

返回此字段的宽度

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

精度¶

返回此字段的数字精度。对于非数字字段，此值没有意义（并设置为零）

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

驱动程序¶

类 驱动程序(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 的字符串，也可以是包含 WKB 数据的 buffer，或者 OGRGeomType 对象。从 Feature.geom 属性返回这些对象，从 Layer（它反过来是 DataSource 的一部分）读取矢量数据时也会返回这些对象。

类方法 from_gml(gml_string)¶

从给定的 GML 字符串构建 OGRGeometry。

类方法 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 字符串或整数 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 坐标，如果该点没有 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

名称¶

返回 OGR 几何类型的简写字符串形式

>>> gt1.name
'Polygon'

数字¶

返回与 OGR 几何类型相对应的数字

>>> gt1.num
3

django¶

返回用于存储此 OGR 类型的 Django 字段类型（GeometryField 的子类），如果不存在合适的 Django 类型，则返回 None

>>> gt1.django
'PolygonField'

包络¶

类 包络(*参数)¶

表示包含矩形边框的最小和最大 X、Y 坐标的 OGR 包络结构。变量的命名与 OGR 包络 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()¶

此方法检查此 SpatialReference 的 WKT，并在 EPSG 标识符适用的地方添加 EPSG 权限节点。

from_esri()¶

将此 SpatialReference 从 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。

线性名称¶

返回线性单位的名称。

线性单位¶

返回线性单位的值。

角度名称¶

返回角度单位的名称。”

角度单位¶

返回角度单位的值。

单位¶

返回单位值和单位名称的 2 元组，并将自动确定返回线性单位还是角度单位。

椭球¶

返回此空间参考的椭球参数元组：(长半轴、短半轴和扁率倒数)。

长半轴¶

返回此空间参考的椭球的长半轴。

短半轴¶

返回此空间参考的椭球的短半轴。

扁率倒数¶

返回此空间参考的椭球的扁率倒数。

地理¶

如果此空间参考是地理参考（根节点是 GEOGCS），则返回 True。

local¶

如果此空间参考是本地的（根节点是 LOCAL_CS），则返回 True。

projected¶

如果此空间参考是投影坐标系（根节点是 PROJCS），则返回 True。

wkt¶

返回此空间参考的 WKT 表示形式。

pretty_wkt¶

返回 WKT 的“漂亮”表示形式。

proj¶

返回此空间参考的 PROJ 表示形式。

proj4¶

别名，用于 SpatialReference.proj。

xml¶

返回此空间参考的 XML 表示形式。

CoordTransform¶

类 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 虚拟文件系统）的字符串或 Path，定义新栅格的值的字典或表示栅格文件的字节对象。

如果输入是文件路径，则从那里打开栅格。如果输入是字典中的原始数据，则需要 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'

在 Django 4.2 中更改

增加了对 pathlib.Path ds_input 的支持。

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 实例的光栅空间参考系统。可以通过将其设置为其他 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、原点、比例、倾斜、数据类型、驱动程序和名称（文件名）。

默认情况下，变形函数将大多数参数保持为原始源栅格的值，因此只需要指定需要更改的参数。请注意，这包括驱动程序，因此对于基于文件的栅格，变形函数将在磁盘上创建一个新的栅格。

唯一与源栅格设置不同的参数是名称。栅格名称的默认值是源栅格的名称，附加 '_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 表示形式。对于未存储在 GDAL 虚拟文件系统中的栅格，返回 None。

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，则统计信息将直接从数据中计算，并且缓存将使用结果进行更新。

如果找到持久缓存值，则返回该值。对于使用持久辅助元数据 (PAM) 服务的栅格格式，统计信息可能缓存在辅助文件中。在某些情况下，此元数据可能与像素值不同步，或导致返回来自先前调用的值，而这些值并不反映 approximate 参数的值。在这种情况下，使用 refresh 参数获取更新的值并将其存储在缓存中。

对于空波段（其中所有像素值均为“无数据”），所有统计信息均返回为 None。

还可以通过访问 min、max、mean 和 std 属性直接检索统计信息。

min¶

波段的最小像素值（不包括“无数据”值）。

max¶

波段的最大像素值（不包括“无数据”值）。

mean¶

波段的所有像素值的平均值（不包括“无数据”值）。

std¶

波段的所有像素值的标准差（不包括“无数据”值）。

nodata_value¶

波段的“无数据”值通常是用来标记无效数据的像素的特殊标记值。此类像素通常不应显示，也不应参与分析操作。

要删除现有的“无数据”值，请将此属性设置为 None。

datatype(as_string=False)¶

波段中包含的数据类型，介于 0（未知）和 14 之间的整数常量。如果 as_string 为 True，则数据类型将作为字符串返回。查看 数据类型值表 中的“GDAL 像素类型”列以了解可能的值。

color_interp(as_string=False)¶

波段的颜色解释，介于 0 到 16 之间的整数。如果 as_string 为 True，则数据类型将作为字符串返回，其可能值为：GCI_Undefined、GCI_GrayIndex、GCI_PaletteIndex、GCI_RedBand、GCI_GreenBand、GCI_BlueBand、GCI_AlphaBand、GCI_HueBand、GCI_SaturationBand、GCI_LightnessBand、GCI_CyanBand、GCI_MagentaBand、GCI_YellowBand、GCI_BlackBand、GCI_YCbCr_YBand、GCI_YCbCr_CbBand 和 GCI_YCbCr_CrBand。 GCI_YCbCr_CrBand 也表示 GCI_Max，因为两者都对应于整数 16，但只有 GCI_YCbCr_CrBand 会作为字符串返回。

data(data=None, offset=None, size=None, shape=None)¶

GDALBand 的像素值访问器。如果未提供任何参数，则返回完整的数据数组。可以通过指定偏移量和块大小（作为元组）来请求像素数组的子集。

如果 NumPy 可用，则数据将作为 NumPy 数组返回。出于性能原因，强烈建议使用 NumPy。

如果提供了 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 类的相应属性和方法的文档。

使用 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）时才使用此设置。