GDAL API

GDAL は Geospatial Data Abstraction Library の略であり、GIS データ機能の真の「スイス・アーミーナイフ」とも言える存在です。GDAL のサブセットには、標準フォーマットでのベクトル地理データの読み書きに特化した OGR Simple Features ライブラリがあります。

GeoDjango は、ベクトル空間データの読み込みと座標変換、ラスタ (画像) データに関する GDAL の機能の最小限のサポートを含む、OGR の機能の一部に対する高レベルの Python インタフェースを提供します。

注釈

モジュールの名前は gdal ですが、GeoDjangoは現時点ではOGRの一部機能とGDALのラスタ機能のみをサポートしています。

概要

サンプルデータ

ここで説明する GDAL/OGR ツールは、地理空間データの読み込みを支援するように設計されています。もしあなたが使い始めたばかりで、まだ自分で使えるデータを持っていないのなら、GeoDjango のテストにはテストに使えるデータセットがたくさん含まれています。以下からダウンロードできます:

$ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/cities/cities.{shp,prj,shx,dbf}
$ wget https://raw.githubusercontent.com/django/django/main/tests/gis_tests/data/rasters/raster.tif

ベクトルデータソースオブジェクト

DataSource

DataSource は OGR データソースオブジェクトのラッパーであり、OGR がサポートする様々な地理空間ファイルフォーマットやデータソースから一貫したインターフェースを使用してデータを読み込むことをサポートします。各データソースは DataSource オブジェクトで表現され、1つ以上のデータのレイヤーを含みます。各レイヤーは Layer オブジェクトで表現され、いくつかの地理情報フィーチャ (Feature) 、そのレイヤーに含まれるフィーチャ (feture) の種類 (ポイント、ポリゴンなど) に関する情報、およびそのレイヤー内の各フィーチャに関連付けられた追加フィールド (Field) の名前とデータ型を含みます。

class DataSource(ds_input, encoding='utf-8')[ソース]

データソース DataSource のコンストラクタに必要なパラメータは1つだけです。しかし、OGRはデータベースを含むより複雑なデータソースもサポートしており、パスの代わりに特別な名前文字列を渡すことでアクセスできます。詳細は OGR Vector Formats のドキュメントを参照してください。 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

上記で読み込まれた都市データソースからの例の出力は、明らかに1つのレイヤーである "cities" を含み、その中に3つのポイント・フィーチャが含まれています。以下の例は簡略化のため、そのレイヤーを変数 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 の feture をラップします。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()

フィールドの値を 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ベクタードライバーの数を返します。

OGR ジオメトリ

OGRGeometry

OGRGeometry オブジェクトは GEOSGeometry オブジェクトと同様の機能を持ち、OGR の内部ジオメトリ表現の薄いラッパーです。そのため、 DataSource を使用する場合、より効率的にデータにアクセスできます。GEOSとは異なり、OGRGeometry は空間参照系 (spatial reference system) と座標変換をサポートしています。

>>> 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 になります。

Deprecated since version 5.1: coord_dim セッターは非推奨です。代わりに set_3d() を使用してください。

is_3d[ソース]

New in Django 5.1.

このジオメトリが Z 座標を持っているかどうかを示す真偽値。

set_3d(value)[ソース]

New in 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[ソース]

New in Django 5.1.

このジオメトリが M 座標を持っているかどうかを示す真偽値。

set_measured(value)[ソース]

New in 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

has_curve[ソース]

New in Django 5.2.

このジオメトリがカーブジオメトリであるか、またはカーブジオメトリを含んでいるかどうかを示すブール値です。

get_linear_geometry()[ソース]

New in Django 5.2.

ジオメトリの線形バージョンを返します。変換ができない場合は、元のジオメトリがそのまま返されます。

get_curve_geometry()[ソース]

New in Django 5.2.

ジオメトリの曲線バージョンを返します。変換できない場合は、元のジオメトリがそのまま返されます。

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[ソース]

このジオメトリの外接矩形を Envelope オブジェクトではなく、4値タプルとして返します。

>>> 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 を返します。

Changed in 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

New in 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

New in 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 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)[ソース]

空間参照系 (spatial reference) オブジェクトは与えられた 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()[ソース]

この空間参照系 (SpatialReference) オブジェクトのクローンを返します。

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 のきれい ("pretty") な表現を返します。

proj[ソース]

この空間参照系の PROJ 表現を返します。

proj4[ソース]

SpatialReference.proj のエイリアス。

xml[ソース]

この空間参照系の XML 表現を返します。

CoordTransform

class CoordTransform(source, target)[ソース]

座標系の変換を表します。ソースとターゲットの座標系をそれぞれ表す2つの 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ラスターソースオブジェクトのラッパーです。各データソースは、1つ以上のデータ層である「bands（バンド）」という名前のデータを含む GDALRaster オブジェクトによって表されます。各バンドは、ジオリファレンスされた画像データを含む GDALBand オブジェクトによって表されます。例えば、RGB画像は、赤、緑、青の各色に対応する3つのバンドで表されます。

注釈

ラスターデータにおいては、ラスターインスタンスとそのデータソースとの間に差異はありません。ジオメトリオブジェクトと異なり、GDALRaster オブジェクトは常にデータソースです。一時的なラスターは、対応するドライバーを使用してメモリ内にインスタンス化できますが、ファイルベースのラスターソースと同じクラスになります。

class GDALRaster(ds_input, write=False)[ソース]

GDALRaster のコンストラクターは 2 つのパラメーターを受け取ります。最初のパラメーターはラスターのソースを定義し、2 番目のパラメーターはラスターを書き込みモードで開くかどうかを定義します。新しく作成されたラスターに対しては、2 番目のパラメーターは無視され、常に書き込みモードで新しいラスターが作成されます。

最初のパラメータは、３つの形式を取ることができます。ファイルパスを表す文字列あるいは 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 Raster Formats リストも参照してください。

インメモリのラスタは次の例のように作成できます:

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

ファイルベースの GeoTiff ラスターは、次の例のように作成できます:

>>> import tempfile
>>> rstfile = tempfile.NamedTemporaryFile(suffix=".tif")
>>> rst = GDALRaster(
...     {
...         "driver": "GTiff",
...         "name": rstfile.name,
...         "srid": 4326,
...         "width": 255,
...         "height": 255,
...         "nr_of_bands": 1,
...     }
... )
>>> rst.name
'/tmp/tmp7x9H4J.tif'           # The exact filename will be different on your computer
>>> rst.driver.name
'GTiff'

width[ソース]

ピクセル単位のソースの幅(X軸)。

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

height[ソース]

ピクセル単位のソースの高さ(Y軸)。

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

srs[ソース]

ラスターの空間参照系を SpatialReference インスタンスとして返します。SRSは他の SpatialReference に設定したり、 SpatialReference コンストラクタが受け付ける任意の入力を与えることで変更できます。

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

srid[ソース]

ラスタの空間参照システム識別子(SRID)。このプロパティは 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[ソース]

以下のリレーションシップを使用して、ピクセル/ライン座標をジオリファレンス空間にマッピングする6つの係数のタプルとして表現されるアフィン変換行列:

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 の使用方法はクラスコンストラクタの対応する引数と同様です。 ds_input はターゲットとなるラスターの特性を辞書に格納したものです。指定できる辞書のキーは width, height, SRID, origin, scale, skew, datatype, driver, name (filename) です。

デフォルトでは、warp 関数はほとんどのパラメータを元のソースラスタの値と等しく保ちます。したがって、変更する必要のあるパラメータのみを指定すればよいです。ただし、これにはドライバも含まれるので、ファイルベースのラスタの場合、warp 関数は新しいラスタをディスク上に作成します。

ソースラスタと異なるパラメータは名前のみです。ラスタ名のデフォルト値は、ソースラスタの名前に '_copy' + source_driver_name を追加したものです。ファイルベースのラスタの場合は、ターゲットとなるラスタのファイルパスを指定することを推奨します。

変形に使用するリサンプリングアルゴリズムは resampling 引数で指定します。デフォルトは NearestNeighbor で、他に指定できる値は Bilinear、Cubic、CubicSpline、Lanczos、Average、Mode です。

max_error 引数は、変換の近似において許容される入力ピクセルでの最大誤差を指定するために使用できます。デフォルト値は正確な計算のために 0.0 です。

GDAL に詳しいユーザーにとって、この関数は gdalwarp コマンドラインユーティリティと同様の機能を持っています。

たとえば、warp 関数は、ラスターを元のピクセルスケールの2倍に集約するために使用できます:

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

このラスタのメタデータ。ネストした辞書として表現されます。第1レベルのキーはメタデータ・ドメインです。第2レベルには、各ドメインのメタデータ項目名と値が含まれます。

メタデータ項目を設定または更新するには、上記の入れ子構造を使用して、対応するメタデータ項目をメソッドに渡します。指定された辞書にあるキーのみが更新され、メタデータの残りの部分は変更されません。

メタデータ項目を削除するには、メタデータの値として 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 属性を介して取得されます。 GDALBand にはラスターの実際のピクセル値が含まれています。

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 引数を使用して更新された値を取得し、キャッシュに保存します。

空のバンド (すべてのピクセル値が "no data "である) の場合、すべての統計は None として返されます。

統計情報は、min、max、mean、および std プロパティにアクセスすることで直接取得することもできます。

min

バンドの最小ピクセル値 ("no data" 値を除く) 。

max

バンドの最大ピクセル値 ("no data" 値を除く) 。

mean

バンドのすべてのピクセル値の平均 ("no data"値を除く) 。

std

バンドのすべてのピクセル値の標準偏差 ("no data" の値を除く)。

nodata_value

バンドの "no data" 値は通常、有効なデータではないピクセルを示す特別なマーカー値です。これらのピクセルは一般的に表示されるべきではなく、分析操作にも寄与すべきではありません。

既存の "no data" 値を削除するには、このプロパティを None に設定します。

datatype(as_string=False)

バンドに含まれるデータ型。0 (Unknown) から 14 までの整数定数。 as_string が True の場合、データ型は文字列として返されます。指定可能な値については、 datatype の値テーブル の "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 パラメータを指定する必要があります。shapeは入力データの幅と高さをピクセル単位で指定するタプルです。その後、選択されたブロックのピクセル値を更新するためにデータが複製されます。これは、たとえば1つの値でバンド全体を塗りつぶすのに便利です。

例:

>>> 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 パラメータを使用してゼロからラスタを作成する方法について説明します。

GDALRaster コンストラクタに dict を渡すことで新しいラスタが作成されます。この辞書には、新しいラスタの定義パラメータ (原点、サイズ、空間参照システムなど) が含まれています。さらに、辞書にはピクセルデータや新しいラスタのフォーマットに関する情報も含めることができます。したがって、作成されるラスタは指定したドライバに応じてファイルベースまたはメモリベースとなります。

ラスターデータを辞書や 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	8 ビット符号なし整数
2	GDT_UInt16	16 ビット符号なし整数
3	GDT_Int16	16ビット符号付き整数
4	GDT_UInt32	32ビット符号なし整数
5	GDT_Int32	32ビット符号付き整数
6	GDT_Float32	32ビット浮動小数点
7	GDT_Float64	64ビット浮動小数点
12	GDT_UInt64	64ビット符号なし整数 (GDAL 3.5+)
13	GDT_Int64	64ビット符号付き整数 (GDAL 3.5+)
14	GDT_Int8	8ビット符号付き整数 (GDAL 3.7+)

nr_of_bands

ラスターのバンド数を表す整数。作成時にバンドデータを渡さずにラスタを作成することもできます。バンド数が指定されていない場合は、入力 bands の長さから自動的に計算されます。作成後にバンド数を変更することはできません。

bands

バンド入力データを持つ band_input 辞書のリスト。結果のバンドインデックスは、提供されたリストと同じです。バンド入力辞書の定義は以下に示します。バンドデータが提供されない場合、ラスターバンドの値はゼロの配列としてインスタンス化され、"no data" の値は None に設定されます。

papsz_options

ラスターを作成するためのオプションを持つ辞書。入力辞書のキーと値のペアは、ラスターの作成時にドライバーに渡されます。

利用可能なオプションは、ドライバごとのドキュメントに記載されています。

辞書内の値は大文字と小文字を区別しないため、作成時に適切な文字列形式に自動変換されます。

以下の例では、GTiff driver で利用可能なオプションのいくつかを使用しています。結果は、内部タイルスキームを持つ圧縮されたラスターです。内部タイルのブロックサイズは23×23です:

>>> GDALRaster(
...     {
...         "driver": "GTiff",
...         "name": "/path/to/new/file.tif",
...         "srid": 4326,
...         "width": 255,
...         "height": 255,
...         "nr_of_bands": 1,
...         "papsz_options": {
...             "compress": "packbits",
...             "tiled": "yes",
...             "blockxsize": 23,
...             "blockysize": 23,
...         },
...     }
... )

band_input 辞書

ds_input 辞書内の bands キーは band_input 辞書のリストです。各 band_input 辞書には、新しいラスタのバンドに設定されるピクセル値と "no data" 値が含まれている可能性があります。データ配列は新しいラスタの全サイズを持つことも、より小さくなることもあります。新しいラスタより小さい配列の場合、size、shape、および offset キーがピクセル値を制御します。これらの対応するキーは、data() メソッドに渡されます。これらの機能は、そのメソッドでバンドデータを設定するのと同じです。以下の表は使用可能なキーを説明しています。

キー	デフォルト値	使い方
nodata_value	None	nodata_value 属性にマッピングされます。
data	nodata_value と同様または 0	data() メソッドに渡されます
size	ラスターの (width, height)	data() メソッドに渡されます
shape	size と同じ	data() メソッドに渡されます
offset	(0, 0)	data() メソッドに渡されます

GDALの仮想ファイルシステムを使う

GDALはファイルシステムに保存されたファイルにアクセスするだけでなく、圧縮、暗号化、またはリモートファイルなど他の種類のファイルにアクセスを抽象化するための仮想ファイルシステムもサポートしています。

メモリベースの仮想ファイルシステムを使用する

GDALには、メモリをファイルとして扱う内部メモリベースのファイルシステムがあります。これを使用して、 GDALRaster オブジェクトをバイナリファイルバッファーに読み込んだり書き込んだりすることができます。

これは、ラスターがリモートストレージからバッファとして取得されたり、ディスクに書き込まれることなくビューから返されたりするようなWebコンテキストで便利です。

bytes オブジェクトが入力として提供されるか、ファイルパスが /vsimem/ で始まる場合、仮想ファイルシステム内に GDALRaster オブジェクトが作成されます。

入力は、ファイルの bytes としての完全なバイナリ表現である必要があります。例えば、:

# 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'

新しい仮想ファイルベースのラスタをゼロから作成するには、 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 のローカルビルドによっては、他の仮想ファイルシステムもサポートされているかもしれません。提供されたパスの先頭に適切な /vsi*/ 接頭辞を付けることで使用できます。詳細は GDAL Virtual Filesystems documentation を参照してください。

圧縮されたラスタ

ファイルを解凍して結果のラスタをインスタンス化する代わりに、GDAL は /vsizip/, /vsigzip/, /vsitar/ 仮想ファイルシステムを使用して圧縮ファイルに直接アクセスできます:

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

ネットワーク ラスタ

GDALは、それらの機能がビルトインされている限り、オンラインリソースとストレージプロバイダを透過的にサポートできます。

認証なしで公開されたラスターファイルにアクセスするには、/vsicurl/ を使用できます。

>>> from django.contrib.gis.gdal import GDALRaster
>>> rst = GDALRaster("/vsicurl/https://example.com/raster.tif")
>>> rst.name
'/vsicurl/https://example.com/raster.tif'

商用のストレージプロバイダ (/vsis3/ など) の場合、認証やその他の設定を事前に行っておく必要があります (利用可能なオプションについては GDAL Virtual Filesystems documentation を参照してください) 。

設定

GDAL_LIBRARY_PATH

GDALライブラリの場所を指定する文字列。通常、この設定はGDALライブラリが標準以外の場所にある場合にのみ使用されます (例えば /home/john/lib/libgdal.so など) 。

例外

exception GDALException[ソース]

GDAL に関連するエラーを示す基本的な GDAL 例外。

exception SRSException[ソース]

空間参照システムオブジェクトの構築時または使用時にエラーが発生した場合に発生する例外。