第9章 ラスタ リファレンス

目次

9.1. ラスタサポートデータ型
9.2. ラスタ管理
9.3. ラスタ コンストラクタ
9.4. ラスタ アクセサ
9.5. ラスタバンド アクセサ
9.6. ラスタピクセル アクセサとセッター
9.7. ラスタ エディタ
9.8. ラスタバンド エディタ
9.9. ラスタバンド統計情報と解析
9.10. ラスタ出力
9.11. ラスタ処理
9.12. ラスタ処理組み込み関数
9.13. ラスタ演算子
9.14. ラスタ/ラスタバンドの空間関係関数

ここで挙げる関数は、PostGISラスタにとって必要と思われるもので、現在PostGISラスタで有効なものです。一般的なユーザが利用しない、ラスタオブジェクトに対して求められるサポート関数があります。

rasterはラスタデータを格納、解析するためのPostGISの型です。

ラスタファイルからラスタをロードするには「ラスタのロードと生成」を参照して下さい。

このリファレンスにおける例ではダミーラスタのラスタテーブルを使っています。ラスタは次のようなコードで形成しています。

CREATE TABLE dummy_rast(rid integer, rast raster);
INSERT INTO dummy_rast(rid, rast)
VALUES (1,
('01' -- little endian (uint8 ndr)
|| 
'0000' -- version (uint16 0)
||
'0000' -- nBands (uint16 0)
||
'0000000000000040' -- scaleX (float64 2)
||
'0000000000000840' -- scaleY (float64 3)
||
'000000000000E03F' -- ipX (float64 0.5)
||
'000000000000E03F' -- ipY (float64 0.5)
||
'0000000000000000' -- skewX (float64 0)
||
'0000000000000000' -- skewY (float64 0)
||
'00000000' -- SRID (int32 0)
||
'0A00' -- width (uint16 10)
||
'1400' -- height (uint16 20)
)::raster
),
-- Raster: 5 x 5 pixels, 3 bands, PT_8BUI pixel type, NODATA = 0
(2,  ('01000003009A9999999999A93F9A9999999999A9BF000000E02B274A' ||
'41000000007719564100000000000000000000000000000000FFFFFFFF050005000400FDFEFDFEFEFDFEFEFDF9FAFEF' ||
'EFCF9FBFDFEFEFDFCFAFEFEFE04004E627AADD16076B4F9FE6370A9F5FE59637AB0E54F58617087040046566487A1506CA2E3FA5A6CAFFBFE4D566DA4CB3E454C5665')::raster);

9.1. ラスタサポートデータ型

概要

本節では、ラスタ機能をサポートするために作られたPostgreSQLデータ型の一覧を挙げます。

geomval — geom(ジオメトリオブジェクトを保持)とval(ラスタバンドからのピクセル値を倍精度浮動小数点数で保持)の2フィールドからなるデータ型。
ヒストグラム — ST_HistogramとST_ApproxHistogram関数のレコード出力として使われる複合型。
raster — ラスタ空間データ型
reclassarg — ST_Reclass関数への入力として使用する複合型です。再分類の挙動を定義します。
summarystats — ST_SummaryStats関数の出力として使う複合型です。

9.2. ラスタ管理

AddRasterConstraints — ロードされたラスタテーブルの特定のカラムにラスタ制約を追加します。制約には空間参照系、スケール、ブロックサイズ、アラインメント、バンド、バンド型、ラスタカラムが規則正しいブロックかどうかを示すフラグがあります。テーブルは制約が推論されるためのデータがロードされなければなりません。制約の設定が完了するとtrueを返し、問題があると通知を返します。
DropRasterConstraints — ラスタテーブルカラムへの参照であるPostGISラスタ制約を削除します。データの再読み込みやラスタカラムデータの更新の際に使います。
PostGIS_Raster_Lib_Build_Date — Reports full raster library build date.
PostGIS_Raster_Lib_Version — Reports full raster version and build configuration infos.
ST_GDALDrivers — 使用しているGDALライブラリが対応するラスタ書式の一覧を返します。ST_AsGDALRasterを使って出力できるラスタの書式です。

9.3. ラスタ コンストラクタ

ST_AddBand — 与えられたタイプで、与えられた初期値にした新しいバンドを、与えられたインデクス位置に付けたラスタを返します。インデクス位置を指定していない場合には、バンドは末尾に追加されます。
ST_AsRaster — PostGISジオメトリをPostGISラスタに変換します。
ST_Band — 既存のラスタの1つ以上のバンドを新しいラスタとして返します。既存のラスタから新しいラスタを構築する際に使います。
ST_MakeEmptyRaster — 与えられたピクセル範囲(width, height)、左上のX,Y、ピクセルサイズ、回転(scalex, scaley, skewx, skewy)と空間参照系(SRID)が指定された空ラスタ(バンドを持たないラスタ)を返します。ラスタが渡されると、新しいラスタは渡されたラスタと同じサイズ、アラインメント、SRIDになります。SRIDが指定されていない場合には、空間参照系は不明(0)とされます。

9.4. ラスタ アクセサ

ST_GeoReference — 一般的にワールドファイルでみられるGDALまたはESRI書式の地理参照メタデータを返します。デフォルトはGDALです。
ST_Height — ラスタの高さをピクセル単位で返します。
ST_MetaData — ピクセルサイズ、回転(skew)、左上隅位置等のラスタオブジェクトに関する基本的なメタデータを返します。
ST_NumBands — ラスタオブジェクトのバンド数を返します。
ST_PixelHeight — 空間参照系の単位での地理的なピクセルの高さを返します。
ST_PixelWidth — 空間参照系の単位での地理的なピクセルの幅を返します。
ST_ScaleX — 空間参照系の単位での地理的なピクセル幅のX成分を返します。
ST_ScaleY — 空間参照系の単位での地理的なピクセルの高さのY成分を返します。
ST_Raster2WorldCoordX — ラスタの指定した列と行における左上隅の地理座標X値を返します。列と行の番号は1始まりです。
ST_Raster2WorldCoordY — ラスタの指定した列と行における左上隅の地理座標Y値を返します。列と行の番号は1始まりです。
ST_Rotation — ラスタの回転をラジアンで返します。
ST_SkewX — 空間参照のXスキュー(回転パラメータ)を返します。
ST_SkewY — 空間参照のYスキュー(回転パラメータ)を返します。
ST_SRID — ラスタのspatial_ref_sysテーブルで定義されている空間参照系識別番号を返します。
ST_UpperLeftX — 適用されている空間参照系でのラスタの左上隅のX座標値を返します。
ST_UpperLeftY — 適用されている空間参照系でのラスタの左上隅のY座標値を返します。
ST_Width — ラスタの幅をピクセル単位で返します。
ST_World2RasterCoordX — ラスタのワールド空間参照系に基づくポイントジオメトリ(pt)またはX,Y座標値(xw,yw)に対応するラスタの列を返します。
ST_World2RasterCoordY — ラスタのワールド空間参照系に基づくポイントジオメトリ(pt)またはX,Y座標値(xw,yw)に対応するラスタの行を返します。
ST_IsEmpty — ラスタが空(width = 0かつheight = 0)の場合にはTRUEを返します。他の場合にはFALSEを返します。

9.5. ラスタバンド アクセサ

ST_BandMetaData — 指定したラスタバンドの基本的なメタデータを返します。バンド番号を指定しない場合には、1番と仮定します。
ST_BandNoDataValue — 指定されたバンドについてデータが無いことを表現する値を返します。バンド番号を指定しない場合には、1番と仮定します。
ST_BandIsNoData — 指定したバンドがNODATA値で満たされている場合にはTRUEを返します。
ST_BandPath — ファイルシステムに格納されているバンドのシステムファイルパスを返します。バンド番号が指定されていない場合には1番と仮定します。
ST_BandPixelType — 指定したバンドのピクセルタイプを返します。バンド番号が指定されていない場合には、1番と仮定します。
ST_HasNoBand — 指定したバンド番号のバンドが無い場合にTRUEを返します。バンド番号を指定していない場合には、1番と仮定します。

9.6. ラスタピクセル アクセサとセッター

ST_PixelAsPolygon — 指定した行と列のピクセルの境界となるジオメトリを返します。
ST_PixelAsPolygons — 全てのピクセルについて境界となるジオメトリを、ピクセルごとのピクセル値とラスタ座標系のXとYとを付けて返します。
ST_Value — 指定したバンドの指定した列Xと行Yまたはジオメトリポイントに対応するピクセルの値を返します。 バンド番号は1始まりで、指定しない場合には1と仮定します。 exclude_nodata_valueがFALSEに設定された場合には、nodataピクセルを含む全てのピクセルがインタセクトするかが考慮され、値を返します。exclude_nodata_valueを渡さない場合には、ラスタのメタデータから読みます。
ST_SetValue — 指定したバンドの指定した列Xと行Yのピクセルまたは指定したジオメトリポイントとインタセクトするピクセルの値を設定することから得られた変更結果を返します。バンド番号は1始まりで、指定しない場合には1と仮定します。

9.7. ラスタ エディタ

ST_SetGeoReference — 1回の関数呼び出しで6つの地理参照パラメータを設定します。値は空白区切りです。GDALまたはESRI書式の入力を受け付けます。デフォルトはGDALです。
ST_SetRotation — ラスタの回転をラジアン単位で設定します。
ST_SetScale — ピクセルのXとYのサイズを空間参照系の単位で設定します。数値はunits/pixelで、幅、高さの順です。
ST_SetSkew — XとYのスキュー(回転パラメータ)を設定します。引数を1つだけ渡した場合には、XとYは同じ値に設定されます。
ST_SetSRID — ラスタのSRIDを、指定した整数でspatial_ref_sysテーブルで定義されているSRIDに設定します。
ST_SetUpperLeft — ラスタの左上隅の地理参照のX,Y座標値を設定します。
ST_Resample — 指定したリサンプリングアルゴリズム、新しいピクセル範囲、グリッドの角、定義するか他のラスタから借りてきた地理参照属性を使ってリサンプリングを行います。新しいピクセル値は、最近傍補間('NearestNeighbor')、双線形補間('Bilinear')、3次補完('Cubic')、3次スプライン補完('CubicSpline')、ランツォシュ補完('Lanczos')、のいずれかのアルゴリズムを使います。デフォルトは最近傍補完です。
ST_Rescale — スケール(ピクセルサイズ)だけを調整するリサンプリングを行います。新しいピクセル値は、最近傍補間('NearestNeighbor')、双線形補間('Bilinear')、3次補完('Cubic')、3次スプライン補完('CubicSpline')、ランツォシュ補完('Lanczos')、のいずれかのアルゴリズムを使います。デフォルトは最近傍補完です。
ST_Reskew — スキュー(回転パラメタ)の調整によるリサンプリングを行います。新しいピクセル値は、最近傍補間('NearestNeighbor')、双線形補間('Bilinear')、3次補完('Cubic')、3次スプライン補完('CubicSpline')、ランツォシュ補完('Lanczos')、のいずれかのアルゴリズムを使います。デフォルトは最近傍補完です。
ST_SnapToGrid — グリッドにスナップさせるリサンプリングを行います。新しいピクセル値は、最近傍補間('NearestNeighbor')、双線形補間('Bilinear')、3次補完('Cubic')、3次スプライン補完('CubicSpline')、ランツォシュ補完('Lanczos')、のいずれかのアルゴリズムを使います。デフォルトは最近傍補完です。
ST_Transform — ラスタを既知の空間参照系から他の既知の空間参照系に、指定したリサンプリングアルゴリズムで投影変換します。選択肢は、最近傍補間('NearestNeighbor')、双線形補間('Bilinear')、3次補完('Cubic')、3次スプライン補完('CubicSpline')、ランツォシュ補完('Lanczos')、があります。デフォルトは最近傍補完です。

9.8. ラスタバンド エディタ

ST_SetBandNoDataValue — 指定したバンドにNODATAを表現する値を設定します。バンドを指定しない場合は1番と仮定します。NODATA値を持たないようにするには、nodatavalue = NULLとします。
ST_SetBandIsNoData — バンドのisnodataフラグをTRUEにします。ST_BandIsNoData(rast, band) != ST_BandIsNodata(rast, band, TRUE)となり、isnodataフラグが汚れている場合に使用することがあります。バンドを指定しない場合は1番バンドと仮定します。

9.9. ラスタバンド統計情報と解析

ST_Count — ラスタまたはラスタカバレッジの指定したバンドのピクセル数を返します。バンドを指定しない場合は1番と仮定します。exclude_nodata_valueをTRUEに設定している場合には、NODATA値と等しくないピクセルのみを数えます。
ST_Histogram — ラスタまたはラスタカバレッジのビン範囲で分割したデータ分布をまとめるヒストグラムの集合を返します。ビン数を指定しない場合には自動計算されます。
ST_Quantile — ラスタまたはラスタテーブルカバレッジのサンプルまたは母集団の分位数を計算します。値がラスタの25%,50%,75%にあるかを調べることができます。
ST_SummaryStats — ラスタまたはラスタカバレッジの指定したバンドについて、ピクセル数、合計値、平均値、標準偏差、最小値、最大値からなる統計情報の概要を返します。バンドを指定しない場合は1番と仮定します。
ST_ValueCount — ラスタ(またはラスタカバレッジの)指定されたバンドで、指定した値を持つピクセルを対象として、ピクセルバンド値とピクセル数からなるレコードの集合を返します。バンドを指定しない場合は1番と仮定します。デフォルトではNODATA値のピクセルは数えられず、ピクセルの他の値は出力され、ピクセルバンド値は最も近い整数に丸められます。

9.10. ラスタ出力

ST_AsBinary — SRIDメタデータを持たないラスタのWell-Known Binary(WKB)表現を返します。
ST_AsGDALRaster — 指定されたGDALラスタ書式でラスタタイルを返します。ラスタ書式はコンパイルしたライブラリが対応するものです。ライブラリが対応する書式の一覧を得るにはST_GDALRasters()を使います。
ST_AsJPEG — ラスタの選択されたバンドを、単一のJoint Photographic Exports Group (JPEG)画像としてバイト配列で返します。バンドを指定せず、1バンドか3以上のバンドがある場合には、1番バンドを使用します。3バンドのみ指定した場合には、3バンドを使用し、RGBに対応付けます。
ST_AsPNG — ラスタの選択されたバンドを、単一のportable network graphics(PNG)画像としてバイト配列で返します。バンドを指定せず、1バンドか3バンド化4バンドある場合には、全てのバンドを使用します。バンドを指定せず、2バンドか4以上のバンドがある場合には、1番バンドを使用します。対象バンドはRGBまたはRGBAに対応付けられます。
ST_AsTIFF — ラスタの選択されたバンドを、単一のTIFF画像として返します。バンドを指定しない場合には、全てのバンドの使用を試みます。

9.11. ラスタ処理

Box3D — ラスタを囲むボックスのbox3d表現を返します。
ST_Clip — 入力ジオメトリで切り取ったラスタを返します。バンドが指定されていない場合には、全てのバンドが返されます。cropが指定されていない場合はTRUEと仮定され、出力ラスタをクロップします。
ST_ConvexHull — BandNoDataValueと等しいピクセル値を含むラスタの凸包ジオメトリを返します。一般的な形状で回転していないラスタでは、ST_Envelopeと同じ結果になります。不規則な形状をしているか回転しているラスタでのみ使います。
ST_DumpAsPolygons — 指定されたラスタバンドからgeomval(geom,val)行の集合を返します。バンドを指定しない場合のデフォルトは1番です。
ST_Envelope — ラスタの範囲のポリゴン表現を返します。
ST_HillShade — 方位、高度、輝度、標高スケールの入力を使って、標高ラスタバンドの仮定的な光による明暗を返します。地形の視覚化に使用します。
ST_Aspect — 標高ラスタバンドの斜面方位を返します。地形解析に使います。
ST_Slope — 標高ラスタバンドの傾斜角を返します。地形解析に使います。
ST_Intersection — 2つのラスタの共有部分またはベクタ化したラスタとジオメトリとのインタセクションを表現する、ラスタまたはジオメトリとピクセル値のペアの集合を返します。
ST_MapAlgebraExpr — 1バンド版: 入力バンドに対する妥当なPostgreSQL代数演算で形成された、指定したピクセルタイプの1バンドのラスタを生成します。バンドを指定しない場合は1番と仮定します。
ST_MapAlgebraExpr — 2バンド版: 2つの入力バンドに対する妥当なPostgreSQL代数演算で形成された、指定したピクセルタイプの1バンドのラスタを生成します。バンドを指定しない場合はどちらも1番と仮定します。結果ラスタは、ひとつめのラスタのアラインメント(スケール、スキュー、ピクセル角位置)にあわされます。範囲は"extenttype"引数で定義されます。取りうる"extenttype"の値はINTERSECTION, UNION, FIRST, SECONDです。
ST_MapAlgebraFct — 1バンド版 - 入力バンドに対する妥当なPostgreSQL関数で形成された、指定したピクセルタイプの1バンドのラスタを生成します。バンドを指定しない場合は1番と仮定します。
ST_MapAlgebraFct — 2ラスタ版 - 2つの入力バンドに対する妥当なPostgreSQL関数で形成された、指定したピクセルタイプの1バンドのラスタを生成します。バンドを指定しない場合は1番と仮定します。"extenttype"のデフォルトはINTERSECTIONです。
ST_MapAlgebraFctNgb — 1バンド版: ユーザ定義PostgreSQL関数を使用する最近傍地図代数関数です。入力ラスタバンドの近傍の値を与えたPL/pgSQLユーザ定義関数の結果からなるラスタを返します。
ST_Polygon — NODATA値でないピクセル値を持つピクセルの結合で形成されるポリゴンジオメトリを返します。バンド番号を設定しない場合には、デフォルトは1番バンドです。
ST_Reclass — 元のラスタから再分類したバンドタイプからなるラスタを生成します。nbandは変更するバンドです。nbandが指定されていない場合は1番と仮定します。他の全てのバンドは変更せずに返します。可視画像の書式としてより単純な描画を行うために、16BUIバンドを8BUIバンドに変換する、等のために使います。
ST_Union — ラスタタイルの集合を1バンドの単一のラスタに結合します。バンドを指定しない場合は1番と仮定します。結果ラスタの範囲は、集合全体の範囲となります。インタセクトする場合には、結果値はp_expressionで定義されます。p_expressionはLAST, MEAN, SUM, FIRST, MAX, MINで、デフォルトはLASTです。

9.12. ラスタ処理組み込み関数

ST_Min4ma — 近傍における最小ピクセル値を計算するラスタ処理関数です。
ST_Max4ma — 近傍における最大ピクセル値を計算するラスタ処理関数です。
ST_Sum4ma — 近傍におけるピクセル値の合計を計算するラスタ処理関数です。
ST_Mean4ma — 近傍におけるピクセル値の平均を計算するラスタ処理関数です。
ST_Range4ma — 近傍におけるピクセル値の範囲合計を計算するラスタ処理関数です。
ST_Distinct4ma — 近傍における一意となるピクセル値の数を計算するラスタ処理関数です。 Raster processing function that calculates the number of unique pixel values in a neighborhood.
ST_StdDev4ma — 近傍におけるピクセル値の標準偏差を計算するラスタ処理関数です。

9.13. ラスタ演算子

&& — のバウンディングボックスがBのバウンディングボックスをオーバラップする場合にTRUEを返します。
&< — AのバウンディングボックスがBのバウンディングボックスをオーバラップするか、Bのバウンディングボックスの左にある場合にTRUEを返します。
&> — AのバウンディングボックスがBのバウンディングボックスをオーバラップするか、Bのバウンディングボックスの右にある場合にTRUEを返します。

9.14. ラスタ/ラスタバンドの空間関係関数

ST_Intersects — バンド番号が省略された場合はラスタの凸包を考慮するだけです。指定したバンドのNODATA値でない値を持つピクセルがインタセクトする場合のみTRUEを返します。
ST_SameAlignment — ラスタが同じスキュー、スケール、空間参照系を持つ場合にはTRUEを返し、そうでない場合は問題を詳述する通知とともにFALSEを返します。