範例資料¶

此處描述的 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 向量格式文件。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 物件中擷取它們，這基本上是一個標準的 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 實例、四元組範圍或 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()¶

以雙精度浮點數 (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 幾何 類別的封裝。這些物件直接從給定的 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。

已於 5.1 版棄用: coord_dim 設定器已棄用。請改用 set_3d()。

is_3d[原始碼]¶

Django 5.1 新增功能。

一個布林值，指示此幾何圖形是否具有 Z 坐標。

set_3d(value)[原始碼]¶

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[原始碼]¶

Django 5.1 新增功能。

一個布林值，指示此幾何圖形是否具有 M 坐標。

set_measured(value)[原始碼]¶

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[原始碼]¶

傳回此幾何圖形中的元素數量

>>> 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 物件。

centroid[原始碼]¶

返回一個 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 坐標，如果點沒有 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)[原始碼]¶

此類別允許以多種方式表示 OGR 幾何圖形類型

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

name[原始碼]¶

返回 OGR 幾何圖形類型的簡短字串形式

>>> gt1.name
'Polygon'

num¶

返回與 OGR 幾何圖形類型對應的數字

>>> gt1.num
3

django[原始碼]¶

傳回用於儲存此 OGR 類型的 Django 欄位類型（GeometryField 的子類別），如果沒有適當的 Django 類型則傳回 None。

>>> 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 Well Known Text (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。

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 表示法。

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 的建構函式接受兩個參數。第一個參數定義網格來源，第二個參數定義是否應以寫入模式開啟網格。對於新建立的網格，將忽略第二個參數，並且新網格始終以寫入模式建立。

第一個參數可以採用三種形式：一個字串或 Path，表示檔案路徑（檔案系統或 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'

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 的使用方式與類別建構子的對應參數類似。它是一個包含目標柵格特性的字典。允許的字典鍵值包括 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)[原始碼]¶

將此柵格轉換為不同的空間參考系統 (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¶

此光柵的 metadata，以巢狀字典表示。第一層鍵是 metadata 域。第二層包含來自每個域的 metadata 項目名稱和值。

若要設定或更新 metadata 項目，請使用上述巢狀結構將對應的 metadata 項目傳遞給方法。只會更新指定字典中的鍵；其餘的 metadata 會保持不變。

若要移除 metadata 項目，請使用 None 作為 metadata 值。

>>> 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 物件取得。GDALBand 包含光柵的實際像素值。

description¶

頻帶的名稱或描述（如果有的話）。

width¶

頻帶的寬度（以像素為單位）（X 軸）。

height¶

頻帶的高度（以像素為單位）（Y 軸）。

pixel_count¶

此頻帶中的像素總數。等於 width * height。

statistics(refresh=False, approximate=False)¶

計算此頻帶像素值的統計資料。傳回值為一個具有下列結構的元組：(最小值、最大值、平均值、標準差)。

如果 approximate 參數設定為 True，統計資料可能會根據概觀或影像圖磚的子集進行計算。

如果 refresh 參數設定為 True，統計資料將直接從資料計算，並且快取將以結果更新。

如果找到持續快取值，則會傳回該值。對於使用持續輔助 Metadata (PAM) 服務的光柵格式，統計資料可能會快取在輔助檔案中。在某些情況下，此 metadata 可能會與像素值不同步，或導致傳回先前呼叫的值，而這些值未反映 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）才使用此設定。