示例数据¶

此处描述的 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')[source]¶

DataSource 的构造函数只需要一个参数：您要读取的文件的路径。但是，OGR 还支持各种更复杂的数据源，包括数据库，可以通过传递特殊名称字符串而不是路径来访问这些数据源。有关更多信息，请参阅 OGR 矢量格式 文档。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[source]¶

返回数据源中层的数量。

name[source]¶

返回数据源的名称。

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 数据源，显然包含一层，名为 "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对象的Layer.num_fields属性。

fields¶

返回与要素关联的数据字段名称列表。对于给定图层中的所有要素，这将是相同的，并且等效于要素来源的Layer对象的Layer.fields属性。

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

将字段的值作为双精度浮点数（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)[source]¶

Driver类在内部用于包装OGR DataSource驱动程序。

driver_count[source]¶

返回当前注册的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)[source]¶

此对象是 OGR Geometry 类的包装器。这些对象直接从给定的 geom_input 参数实例化，该参数可以是包含 WKT、HEX、GeoJSON 的字符串，包含 WKB 数据的 buffer，或 OGRGeomType 对象。这些对象也从 Feature.geom 属性返回，当从 Layer（它是 DataSource 的一部分）读取矢量数据时。

classmethod from_gml(gml_string)[source]¶

从给定的 GML 字符串构造一个 OGRGeometry。

classmethod from_bbox(bbox)[source]¶

从给定的边界框（一个 4 元组）构造一个 Polygon。

__len__()¶

返回 LineString 中的点数、Polygon 中的环数或 GeometryCollection 中的几何图形数。不适用于其他几何类型。

__iter__()¶

迭代 LineString 中的点、Polygon 中的环或 GeometryCollection 中的几何图形。不适用于其他几何类型。

__getitem__()¶

返回 LineString 中指定索引处的点、Polygon 中指定索引处的内部环或 GeometryCollection 中指定索引处的几何图形。不适用于其他几何类型。

dimension[source]¶

返回几何图形的坐标维数，例如，点为 0，线为 1，依此类推。

>>> polygon.dimension
2

coord_dim[source]¶

返回此几何图形的坐标维数。例如，二维几何图形的值将为 2。

自版本 5.1 起已弃用： coord_dim 设置器已弃用。请改用 set_3d()。

is_3d[source]¶

Django 5.1 中的新功能。

一个布尔值，指示此几何图形是否具有 Z 坐标。

set_3d(value)[source]¶

Django 5.1 中的新功能。

一个添加或删除 Z 坐标维数的方法。

>>> p = OGRGeometry("POINT (1 2 3)")
>>> p.is_3d
True
>>> p.set_3d(False)
>>> p.wkt
"POINT (1 2)"

is_measured[source]¶

Django 5.1 中的新功能。

一个布尔值，指示此几何图形是否具有 M 坐标。

set_measured(value)[source]¶

Django 5.1 中的新功能。

一个添加或删除 M 坐标维数的方法。

>>> p = OGRGeometry("POINT (1 2)")
>>> p.is_measured
False
>>> p.set_measured(True)
>>> p.wkt
"POINT M (1 2 0)"

geom_count[source]¶

返回此几何图形中的元素数量。

>>> polygon.geom_count
1

point_count[source]¶

返回描述此几何图形所使用的点数。

>>> polygon.point_count
4

num_points[source]¶

point_count 的别名。

num_coords[source]¶

point_count 的别名。

geom_type[source]¶

返回此几何图形的类型，作为 OGRGeomType 对象。

geom_name[source]¶

返回此几何图形类型的名称。

>>> polygon.geom_name
'POLYGON'

area[source]¶

返回此几何图形的面积，对于不包含面积的几何图形，返回 0。

>>> polygon.area
25.0

envelope[source]¶

返回此几何图形的包络线，作为 Envelope 对象。

extent[source]¶

返回此几何图形的包络线作为 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[source]¶

返回与该几何图形对应的 GEOSGeometry 对象。

gml[source]¶

以 GML 格式返回该几何图形的字符串表示形式。

>>> OGRGeometry("POINT(1 2)").gml
'<gml:Point><gml:coordinates>1,2</gml:coordinates></gml:Point>'

hex[source]¶

以 HEX WKB 格式返回该几何图形的字符串表示形式。

>>> OGRGeometry("POINT(1 2)").hex
'0101000000000000000000F03F0000000000000040'

json[source]¶

以 JSON 格式返回该几何图形的字符串表示形式。

>>> OGRGeometry("POINT(1 2)").json
'{ "type": "Point", "coordinates": [ 1.000000, 2.000000 ] }'

kml[source]¶

以 KML 格式返回该几何图形的字符串表示形式。

wkb_size[source]¶

返回保存该几何图形的 WKB 表示形式所需的 WKB 缓冲区的大小。

>>> OGRGeometry("POINT(1 2)").wkb_size
21

wkb[source]¶

返回包含该几何图形的 WKB 表示形式的 buffer。

wkt[source]¶

以 WKT 格式返回该几何图形的字符串表示形式。

ewkt[source]¶

返回该几何图形的 EWKT 表示形式。

clone()[source]¶

返回该几何图形对象的新的 OGRGeometry 克隆。

close_rings()[source]¶

如果该几何图形中存在任何未闭合的环，则此例程将通过在末尾添加起始点来闭合它们。

>>> 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)[source]¶

将该几何图形转换到不同的空间参考系统。可以接受 CoordTransform 对象、SpatialReference 对象，或 SpatialReference 接受的任何其他输入（包括空间参考 WKT 和 PROJ 字符串，或整数 SRID）。

默认情况下，不返回任何内容，并且几何图形在原位转换。但是，如果 clone 关键字设置为 True，则改为返回该几何图形的已转换克隆。

intersects(other)[source]¶

如果该几何图形与另一个几何图形相交，则返回 True，否则返回 False。

equals(other)[source]¶

如果该几何图形等效于另一个几何图形，则返回 True，否则返回 False。

disjoint(other)[source]¶

如果该几何图形在空间上与另一个几何图形分离（即不相交），则返回 True，否则返回 False。

touches(other)[source]¶

如果该几何图形与另一个几何图形相切，则返回 True，否则返回 False。

crosses(other)[source]¶

如果该几何图形与另一个几何图形交叉，则返回 True，否则返回 False。

within(other)[source]¶

如果该几何图形包含在另一个几何图形内，则返回 True，否则返回 False。

contains(other)[source]¶

如果该几何图形包含另一个几何图形，则返回 True，否则返回 False。

overlaps(other)[source]¶

如果该几何图形与另一个几何图形重叠，则返回 True，否则返回 False。

boundary()[source]¶

该几何图形的边界，作为新的 OGRGeometry 对象。

convex_hull[source]¶

包含该几何图形的最小凸多边形，作为新的 OGRGeometry 对象。

difference()[source]¶

返回由该几何图形与另一个几何图形的差组成的区域，作为新的 OGRGeometry 对象。

intersection()[source]¶

返回由该几何图形与另一个几何图形的交集组成的区域，作为新的 OGRGeometry 对象。

sym_difference()[source]¶

返回此几何图形与另一个几何图形的对称差分区域，作为一个新的 OGRGeometry 对象。

union()[source]¶

返回此几何图形与另一个几何图形的并集区域，作为一个新的 OGRGeometry 对象。

centroid[source]¶

返回一个表示此几何图形质心的 Point 对象。

Django 5.1 中的更改

centroid 从仅适用于 Polygon 的属性升级为所有几何类型都可用。

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

m¶

Django 5.1 中的新功能。

返回此点的 M 坐标，如果 Point 没有 M 坐标，则返回 None。

>>> OGRGeometry("POINT ZM (1 2 3 4)").m
4.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]

m¶

Django 5.1 中的新功能。

返回此线中的 M 坐标列表，如果线没有 M 坐标，则返回 None。

>>> OGRGeometry("LINESTRING(0 1 2 10, 1 2 3 11, 2 3 4 12)").m
[10.0, 11.0, 12.0]

class Polygon¶

shell¶

返回此多边形的壳或外部环，作为 LinearRing 几何图形。

exterior_ring¶

是 shell 的别名。

class GeometryCollection¶

add(geom)¶

将几何图形添加到此几何图形集合中。不适用于其他几何图形类型。

OGRGeomType¶

class OGRGeomType(type_input)[source]¶

此类允许以多种方式表示 OGR 几何图形类型。

>>> from django.contrib.gis.gdal import OGRGeomType
>>> gt1 = OGRGeomType(3)  # Using an integer for the type
>>> gt2 = OGRGeomType("Polygon")  # Using a string
>>> gt3 = OGRGeomType("POLYGON")  # It's case-insensitive
>>> print(gt1 == 3, gt1 == "Polygon")  # Equivalence works w/non-OGRGeomType objects
True True

name[source]¶

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

>>> gt1.name
'Polygon'

num¶

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

>>> gt1.num
3

django[source]¶

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

>>> gt1.django
'PolygonField'

Envelope¶

class Envelope(*args)[source]¶

表示一个 OGR Envelope 结构，该结构包含矩形边界框的最小和最大 X、Y 坐标。变量的命名与 OGR Envelope C 结构兼容。

min_x[source]¶

最小 X 坐标的值。

min_y[source]¶

最大 X 坐标的值。

max_x[source]¶

最小 Y 坐标的值。

max_y[source]¶

最大 Y 坐标的值。

ur[source]¶

右上角坐标，作为一个元组。

ll[source]¶

左下角坐标，作为一个元组。

tuple[source]¶

表示信封的元组。

wkt[source]¶

以 WKT 格式表示此信封的多边形字符串。

expand_to_include(*args)[source]¶

SpatialReference¶

class SpatialReference(srs_input)[source]¶

空间参考对象根据给定的 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)[source]¶

返回给定字符串属性节点的值，如果节点不存在则返回 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)[source]¶

给定目标节点（例如 'PROJCS'）的属性值。index 关键字指定要返回的子节点的索引。

auth_name(target)[source]¶

返回给定字符串目标节点的授权名称。

auth_code(target)[source]¶

返回给定字符串目标节点的授权代码。

clone()[source]¶

返回此空间参考对象的克隆。

identify_epsg()[source]¶

此方法检查此 SpatialReference 的 WKT，并在适用时添加 EPSG 授权节点。

from_esri()[source]¶

将此 SpatialReference 从 ESRI 格式转换为 EPSG 格式。

to_esri()[source]¶

将此 SpatialReference 转换为 ESRI 格式。

validate()[source]¶

检查给定的空间参考是否有效，如果无效则会引发异常。

import_epsg(epsg)[source]¶

从 EPSG 代码导入空间参考。

import_proj(proj)[source]¶

从 PROJ 字符串导入空间参考。

import_user_input(user_input)[source]¶

import_wkt(wkt)[source]¶

从 WKT 导入空间参考。

import_xml(xml)[source]¶

从 XML 导入空间参考。

name[source]¶

返回此空间参考的名称。

srid[source]¶

返回顶层授权的 SRID，如果未定义则返回 None。

linear_name[source]¶

返回线性单位的名称。

linear_units[source]¶

返回线性单位的值。

angular_name[source]¶

返回角单位的名称。

angular_units[source]¶

返回角单位的值。

units[source]¶

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

ellipsoid[source]¶

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

semi_major[source]¶

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

semi_minor[source]¶

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

inverse_flattening[source]¶

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

geographic[source]¶

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

local[source]¶

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

projected[source]¶

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

wkt[source]¶

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

pretty_wkt[source]¶

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

proj[source]¶

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

proj4[source]¶

SpatialReference.proj 的别名。

xml[source]¶

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

CoordTransform¶

class CoordTransform(source, target)[source]¶

表示坐标系转换。它使用两个 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)[source]¶

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'

name[source]¶

源的名称，等效于输入文件路径或在实例化时提供的名称。

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

driver[source]¶

用于处理输入文件的 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[source]¶

源的宽度（以像素为单位）（X 轴）。

>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).width
10

height[source]¶

源的高度（以像素为单位）（Y 轴）。

>>> GDALRaster({"width": 10, "height": 20, "srid": 4326}).height
20

srs[source]¶

栅格的空间参考系统，作为 SpatialReference 实例。可以通过将其设置为另一个 SpatialReference 或提供 SpatialReference 构造函数接受的任何输入来更改 SRS。

>>> rst = GDALRaster({"width": 10, "height": 20, "srid": 4326})
>>> rst.srs.srid
4326
>>> rst.srs = 3086
>>> rst.srs.srid
3086

srid[source]¶

栅格的空间参考系统标识符 (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[source]¶

用于对源进行地理配准的仿射变换矩阵，作为一个包含六个系数的元组，使用以下关系将像素/行坐标映射到地理配准空间

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[source]¶

栅格左上角原点在源空间参考系统中的坐标，作为具有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[source]¶

用于对栅格进行地理配准的像素宽度和高度，作为具有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[source]¶

用于对栅格进行地理配准的倾斜系数，作为具有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[source]¶

栅格源的范围（边界值），作为源空间参考系统中的 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[source]¶

源的所有波段的列表，作为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)[source]¶

返回此栅格的扭曲版本。

可以通过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命令行实用程序。

例如，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(srs, driver=None, name=None, resampling='NearestNeighbour', max_error=0.0)[source]¶

将此栅格转换为不同的空间参考系统（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[source]¶

返回包含栅格摘要的字符串。这等效于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[source]¶

此栅格的bytes表示形式。对于未存储在GDAL虚拟文件系统中的栅格，返回None。

is_vsi_based[source]¶

一个布尔值，指示此栅格是否存储在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("https://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）才使用此设置。